Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
/**
* Company-private storage.
*
* Private files live in one bucket PER COMPANY (bucket id = companyId).
* Object keys keep the `${companyId}/...` first segment, so a stored path
* names its own bucket.
*
* const { data, error } = await storage(client).company(companyId).download(path);
* await storage(client).company(companyId).upload(path, file, { upsert: true });
* await storage(client).from("public").upload(path, file);
*/
import {
type DownloadResult,
type FileObject,
type SearchV2Result,
type StorageClient,
StorageError,
type TransformOptions
} from "@supabase/storage-js";
/**
* The URL segment `/file/preview/private/<path>` — a stored link format
* (rich text, inspection documents) that the preview routes serve from the
* caller's own company bucket. The shared `private` bucket it once named no
* longer exists.
*/
export const PRIVATE_PREVIEW_ALIAS = "private";
// Ephemeral staging for uploads too big for a company bucket's per-object cap
// (raw CAD, backup archives). 2.5 GB cap; stale objects are pruned by the
// scheduled cleanup job. Object keys start with the companyId segment.
export const TEMP_STAGING_BUCKET = "temp-staging";
export const COMPANY_BUCKET_FILE_SIZE_LIMIT = 52428800; // 50 MB
export const normalizeStorageSegment = (value: string) =>
value
.trim()
.replace(/[\\/]+/g, "-")
.replace(/^[-/]+|[-/]+$/g, "");
export const getCompanyPrivateBucket = (companyId: string) => {
const bucket = normalizeStorageSegment(companyId);
if (!bucket) {
// `.from("")` would silently probe a non-existent bucket and fall through
// to whatever fallback the caller has — refuse loudly instead.
throw new Error(
"companyId is required to resolve a company private bucket"
);
}
return bucket;
};
export const hasCompanyPrivateObjectPathPrefix = (
companyId: string,
objectPath: string
) => {
const bucket = normalizeStorageSegment(companyId);
return bucket ? objectPath.startsWith(`${bucket}/`) : false;
};
// A well-formed key stops changing after one decode (a key cannot hold a
// literal `%`), so anything still decoding after this many passes is refused.
const MAX_STORAGE_PATH_DECODES = 4;
const isDotSegment = (segment: string) => segment === "." || segment === "..";
const hasUnsafeStorageSyntax = (path: string) => {
if (/[\\?#]/.test(path)) return true;
for (const char of path) {
const code = char.charCodeAt(0);
if (code < 0x20 || code === 0x7f) return true;
}
return path.split("/").some(isDotSegment);
};
/**
* True when an object key could resolve somewhere other than where its text
* says. storage-js puts the key into the request URL UNENCODED, and the WHATWG
* URL parser resolves `.` / `..` segments (percent-encoded `%2e` too), reads
* `\` as `/`, strips tabs and newlines, and ends the path at `?` / `#`. Any of
* those lets a key pass a `${companyId}/` prefix check and then read or write
* another company's object — or another bucket.
*
* The key is checked as given and after every decode until it stops changing,
* so single- and double-encoded traversal (`%2e%2e`, `%252e%252e`) is caught
* wherever a caller sits in the decode chain. A malformed escape is refused:
* storage never accepts a key containing a literal `%`.
*/
export function isUnsafeStoragePath(path: string): boolean {
let current = path;
for (let pass = 0; pass <= MAX_STORAGE_PATH_DECODES; pass++) {
if (hasUnsafeStorageSyntax(current)) return true;
let decoded: string;
try {
decoded = decodeURIComponent(current);
} catch {
return true;
}
if (decoded === current) return false;
current = decoded;
}
return true;
}
/**
* A caller-supplied file name made safe to use as the LAST segment of an
* object key: the basename only (anything before a `/` or `\` is dropped),
* trimmed, with `?`, `#` and `%` removed ("Drawing #3.pdf" → "Drawing 3.pdf",
* the same result `stripSpecialCharacters` gives). Null when nothing usable is
* left or the name fails `isUnsafeStoragePath`.
*/
export function safeStorageFileName(name: string): string | null {
// `?` / `#` would end the key at that character and `%` would be decoded
// into a different key, so they are dropped rather than refusing the upload.
const base = (name.split(/[/\\]/).pop() ?? "")
.replace(/[?#%]/g, "")
.replace(/\s{2,}/g, " ")
.trim();
if (!base || isUnsafeStoragePath(base)) return null;
return base;
}
type Bucket = ReturnType<StorageClient["from"]>;
/**
* A company's private bucket with the supabase `StorageFileApi` shape. Every
* key must sit under `${companyId}/`: a company bucket must never hold a key
* that `getPrivateUrl` would resolve to another company's bucket.
*
* `list(folder)` returns EVERY entry directly inside the folder, sorted by
* name, in the shape the old list endpoint used (a sub-folder is an entry with
* a null `id`). It takes no options — it reads the cursor-paged list endpoint
* to the end, so there is no limit or offset to pass.
*
* Deliberately absent: `getPublicUrl` (private bucket) and `createSignedUrls`.
* Use `.from()` if one is ever needed.
*/
export type CompanyBucket = {
upload: Bucket["upload"];
update: Bucket["update"];
uploadToSignedUrl: Bucket["uploadToSignedUrl"];
move: Bucket["move"];
copy: Bucket["copy"];
createSignedUploadUrl: Bucket["createSignedUploadUrl"];
exists: Bucket["exists"];
info: Bucket["info"];
download(
path: string,
options?: { transform?: TransformOptions }
): Promise<DownloadResult<Blob>>;
createSignedUrl: Bucket["createSignedUrl"];
list(folder: string): ReturnType<Bucket["list"]>;
remove(paths: string[]): ReturnType<Bucket["remove"]>;
};
export type CarbonStorage = {
/** Any other bucket (`public`, `temp-staging`, …) — plain supabase. */
from(bucket: string): Bucket;
company(companyId: string): CompanyBucket;
};
/**
* What to say when a storage image transform fails. Storage hands transforms
* to imgproxy, and when that service is not running the failure names it
* (`getaddrinfo ENOTFOUND imgproxy`) — a stack problem, not a bad image, and
* the local dev stack leaves imgproxy off by default. Anything else gets the
* caller's own message.
*/
export function imageTransformErrorMessage(
error: unknown,
fallback: string
): string {
const message = (error as { message?: unknown } | null)?.message;
return typeof message === "string" && /imgproxy/i.test(message)
? "Image transformation is unavailable: storage cannot reach imgproxy. On the local dev stack, start it with `crbn reload imgproxy` or boot with `crbn up --full`."
: fallback;
}
/**
* The HTTP status behind a storage error. `download()` skips reading the
* error body, so a 400/404 arrives as `StorageUnknownError("{}")` with the
* status only on the raw response in `originalError`.
*/
export function storageErrorStatus(error: unknown): number | undefined {
if (!error || typeof error !== "object") return undefined;
const { status, originalError } = error as {
status?: unknown;
originalError?: { status?: unknown };
};
if (typeof status === "number") return status;
return typeof originalError?.status === "number"
? originalError.status
: undefined;
}
/**
* Whether a storage error means the object (or bucket) is not there. Storage
* answers a miss with HTTP 400 and `"statusCode":"404"` in the body, the same
* status it uses for an invalid key or request — so a 400 counts only when
* its body says 404. `download()` never reads that body, so it is still
* unread on `originalError`.
*/
export async function isStorageNotFound(error: unknown): Promise<boolean> {
if (!error || typeof error !== "object") return false;
const { statusCode, originalError } = error as {
statusCode?: unknown;
originalError?: unknown;
};
if (statusCode === "404" || storageErrorStatus(error) === 404) return true;
if (!(originalError instanceof Response) || originalError.status !== 400) {
return false;
}
const body = await originalError
.clone()
.json()
.catch(() => null);
return body?.statusCode === "404";
}
const lastSegment = (path: string) =>
path.replace(/\/+$/, "").split("/").pop() ?? "";
// What the old endpoint returned for a folder, and every caller checks:
// the paged endpoint gives a folder only its name and key.
const FOLDER_FIELDS = {
id: null,
updated_at: null,
created_at: null,
last_accessed_at: null,
metadata: null
};
type ListedEntry =
| (SearchV2Result["folders"][number] & typeof FOLDER_FIELDS)
| SearchV2Result["objects"][number];
/**
* The cursor-paged endpoint names an entry by its full key; callers expect the
* old endpoint's shape, where `name` is the entry's own name inside the folder.
*/
function toFileObjects(entries: ListedEntry[]): FileObject[] {
return entries.map((entry) => ({
...entry,
name: lastSegment(entry.key ?? entry.name)
})) as unknown as FileObject[];
}
/** Everything directly inside `prefix`, read to the last page. */
async function listFolder(bucket: Bucket, prefix: string) {
const entries: ListedEntry[] = [];
let cursor: string | undefined;
do {
const { data, error } = await bucket.listV2({
prefix,
with_delimiter: true,
cursor
});
if (error) return { data: null, error };
entries.push(
...data.folders.map((folder) => ({ ...FOLDER_FIELDS, ...folder })),
...data.objects
);
if (!data.hasNext) break;
// More pages promised with no way to reach them: a repeated cursor would
// loop forever, a missing one would pass a partial list off as complete.
if (!data.nextCursor || data.nextCursor === cursor) {
return {
data: null,
error: new StorageError(`Listing "${prefix}" did not advance`)
};
}
cursor = data.nextCursor;
} while (cursor);
const files = toFileObjects(entries).sort((a, b) =>
a.name < b.name ? -1 : a.name > b.name ? 1 : 0
);
return { data: files, error: null };
}
export function storage(client: { storage: StorageClient }): CarbonStorage {
return {
from: (bucket) => client.storage.from(bucket),
company: (companyId) => companyBucket(client.storage, companyId)
};
}
function companyBucket(
storage: StorageClient,
companyId: string
): CompanyBucket {
const id = getCompanyPrivateBucket(companyId);
const own = storage.from(id);
// The prefix is only a boundary if the key cannot climb out of it. Storage
// uses the key only up to the first `?` / `#` (the URL parser ends the path
// there), so that is the key checked: cutting a suffix off a key that starts
// with `${companyId}/` cannot leave the company, and a name like
// "Drawing #3.pdf" keeps uploading exactly as it always has.
const owned = (path: string) => {
const key = path.split(/[?#]/, 1)[0] ?? "";
return (
hasCompanyPrivateObjectPathPrefix(companyId, key) &&
!isUnsafeStoragePath(key)
);
};
const owns = (...paths: string[]) => paths.every(owned);
const refuse = (...paths: string[]) =>
Promise.resolve({
data: null,
error: new StorageError(
`${paths.filter((path) => !owned(path)).join(", ")} is outside the "${id}/" storage prefix`
)
});
return {
upload: (path, ...rest) =>
owns(path) ? own.upload(path, ...rest) : refuse(path),
update: (path, ...rest) =>
owns(path) ? own.update(path, ...rest) : refuse(path),
uploadToSignedUrl: (path, ...rest) =>
owns(path) ? own.uploadToSignedUrl(path, ...rest) : refuse(path),
move: (from, to, options) =>
owns(from, to) ? own.move(from, to, options) : refuse(from, to),
copy: (from, to, options) =>
owns(from, to) ? own.copy(from, to, options) : refuse(from, to),
createSignedUploadUrl: (path, options) =>
owns(path) ? own.createSignedUploadUrl(path, options) : refuse(path),
exists: (path) =>
owns(path)
? own.exists(path)
: refuse(path).then(({ error }) => ({ data: false, error })),
info: (path) => (owns(path) ? own.info(path) : refuse(path)),
download: (path, options) =>
owns(path) ? own.download(path, options) : refuse(path),
createSignedUrl: (path, expiresIn, options) =>
owns(path) ? own.createSignedUrl(path, expiresIn, options) : refuse(path),
list: (folder) =>
owns(folder)
? // The endpoint matches a plain key prefix, so without the trailing
// slash it would answer with the folder itself rather than what is
// inside it.
listFolder(own, `${folder.replace(/\/+$/, "")}/`)
: refuse(folder),
remove: (paths) => (owns(...paths) ? own.remove(paths) : refuse(...paths))
};
}