@pithy-sh/storage 0.1.0

package/src/error/errors.ts

@@ -0,0 +1,140 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { MessageParams } from "@pithy-sh/core/src/i18n/catalog";
+
+/**
+ * `@pithy-sh/storage` throw sugar. The `storage/*` codes live in core's closed `KitErrorPayload` union
+ * (CLAUDE.md §Errors); these subclasses are the package-local vehicles that set one of those members.
+ * Runtime code in this package throws one of these, never a plain `new Error`.
+ *
+ * Public text goes in `message` and `action`; throw-site context goes in `detail`, which the HTTP
+ * codec strips. That matters more here than in most capabilities: object keys, upload ids, and byte
+ * counts are exactly the kind of internal shape a client should never be handed.
+ */
+
+interface StorageErrorArgs {
+  message?: string;
+  action?: string;
+  detail?: string;
+  /**
+   * Values a translating client interpolates into its own wording for this code. Client-facing, so —
+   * unlike `action` and `detail` — these cross the boundary with `message`.
+   */
+  params?: MessageParams;
+}
+
+export class StorageNotFoundError extends PithyError {
+  constructor(args: StorageErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "storage/not_found",
+        status: 404,
+        message: args.message ?? "That file does not exist.",
+        action: args.action ?? "Check the object id. A file you do not own reads as missing, not as forbidden.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class StorageForbiddenError extends PithyError {
+  constructor(args: StorageErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "storage/forbidden",
+        status: 403,
+        message: args.message ?? "That file is not yours.",
+        action: args.action ?? "Sign in as the owner, or ask them for a share link.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class StorageQuotaExceededError extends PithyError {
+  constructor(args: StorageErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "storage/quota_exceeded",
+        status: 413,
+        message: args.message ?? "That upload would put you over your storage quota.",
+        action: args.action ?? "Delete something first, or raise the quota in pithy.config.ts.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class StorageUploadIncompleteError extends PithyError {
+  constructor(args: StorageErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "storage/upload_incomplete",
+        status: 409,
+        message: args.message ?? "That file has not finished uploading.",
+        action: args.action ?? "Upload every part, then complete the upload.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class StorageMultipartFailedError extends PithyError {
+  constructor(args: StorageErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "storage/multipart_failed",
+        status: 500,
+        // The recovery route is the caller's own answer, so it is in `message`: an `action` is the
+        // operator's sentence and the HTTP codec strips it (#344). A client that cannot see how to
+        // finish an upload it half-made has been told nothing useful.
+        message: args.message ?? "The upload could not be assembled. GET /storage/<id>/parts to see what is missing.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class StorageShareExpiredError extends PithyError {
+  constructor(args: StorageErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "storage/share_expired",
+        status: 410,
+        message: args.message ?? "That share link has expired.",
+        action: args.action ?? "Ask the owner for a new one.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}
+
+export class StorageShareRevokedError extends PithyError {
+  constructor(args: StorageErrorArgs = {}, options?: { cause?: unknown }) {
+    super(
+      {
+        code: "storage/share_revoked",
+        status: 410,
+        message: args.message ?? "That share link was revoked.",
+        action: args.action ?? "Ask the owner for a new one.",
+        detail: args.detail,
+        params: args.params,
+      },
+      options,
+    );
+  }
+}

package/src/http/guard.ts

@@ -0,0 +1,32 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import type { MiddlewareHandler } from "hono";
+
+/**
+ * The storage routes' identity gate.
+ *
+ * **Copied, not imported.** This is deliberately a local copy of the same three lines
+ * `@pithy-sh/media` and `@pithy-sh/ledger` each carry, rather than an import from `@pithy-sh/auth`.
+ * Importing it would make auth a hard dependency of storage, and a hard dependency is the wrong
+ * shape twice over: storage works perfectly well for system-owned objects with no auth capability
+ * composed, and — far more importantly — a package that *imports* its authorization from another
+ * package fails open when that package is absent. Depending on the core `AuthContext` seam instead
+ * means `c.var.auth` is simply `null` with no auth capability composed, and every owner-scoped
+ * route **denies**. Failing closed is not a side effect here; it is the reason for the copy.
+ *
+ * So `dependsOn` stays free of auth and the manifest lists it under `optionalCapabilities`.
+ */
+export function requireAuth(): MiddlewareHandler<PithyHonoEnv> {
+  return async (c, next) => {
+    if (!c.var.auth) {
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Sign in and retry with a valid session or bearer token.",
+      });
+    }
+    await next();
+  };
+}