@12-apps/storage 2.1.0 → 2.2.0

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@12-apps/storage",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "type": "module",
   "description": "Image uploads that land at YOUR OWN ORIGIN, never at the bucket (12-20). Isomorphic core (format allowlist, upload ceiling, object-key grammar, rendition set, refusal taxonomy, wire schemas), host-mounted backend surface (./server: createApiStorage, the local-disk driver, the image-pipeline port, the orphan reclaim), Hono adapter (./hono), the S3-compatible driver behind its own subpath (./s3) and the bound picker + upload hook (./react). Standardized adoption contract in ADOPTING.md.",
   "exports": {
     ".": "./src/index.ts",
-    "./server": "./src/server/index.ts",
-    "./react": "./src/react/index.ts",
     "./hono": "./src/hono/index.ts",
+    "./manifest": "./src/manifest/index.ts",
+    "./manifest/server": "./src/manifest/server.ts",
+    "./package.json": "./package.json",
+    "./react": "./src/react/index.ts",
     "./s3": "./src/s3/index.ts",
-    "./package.json": "./package.json"
+    "./server": "./src/server/index.ts"
   },
   "scripts": {
     "clean": "rm -rf node_modules coverage",
@@ -20,6 +22,7 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
+    "@12-apps/wiring": ">=1.9.0",
     "@aws-sdk/client-s3": ">=3.700.0",
     "hono": ">=4.0.0",
     "react": ">=19.0.0",
@@ -40,12 +43,13 @@
     }
   },
   "dependencies": {
-    "@12-apps/ui": "^6.2.0",
+    "@12-apps/ui": "^6.3.1",
     "zod": "^4.3.5"
   },
   "devDependencies": {
     "@12-apps/eslint-config": "^1.21.1",
     "@12-apps/typescript-config": "^1.20.1",
+    "@12-apps/wiring": "^1.10.0",
     "@aws-sdk/client-s3": "^3.703.0",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",

package/src/manifest/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `@12-apps/storage/manifest` — the SHARED wiring manifest.
+ *
+ * Identity and the runtime inventory. Three absences are deliberate rather
+ * than unfinished:
+ *
+ * - **No `db`.** This package owns no table. What an uploaded object leaves
+ *   behind is a KEY, and the row that key hangs off is the host's own — a
+ *   product image, a store logo — so there is nothing here to compose.
+ * - **No `env`.** `./server`'s own header states the rule this manifest would
+ *   otherwise have to restate: there are no `process.env` reads in shipped
+ *   source, because every deployment-shaped decision (the driver, the byte
+ *   ceiling, the key prefix, the bucket) is an ARGUMENT. A package that reads
+ *   the environment decides for its host; this one asks.
+ * - **No `web` inventory.** The React half is components a host renders, not
+ *   a mountable surface with its own routes.
+ *
+ * `observability` is mandatory here because `http` is: a refused upload or a
+ * driver that could not be reached files under `storage` rather than under
+ * whichever host happened to mount it.
+ *
+ * `@12-apps/wiring` is a TYPE-ONLY devDependency (the report-builder move):
+ * the manifests are plain `satisfies`-checked values, and the producer
+ * factories' runtime assertions run in this package's own test suite.
+ */
+
+import type { PackageManifest } from '@12-apps/wiring';
+
+export const storageManifest = {
+  name: '@12-apps/storage',
+  contract: 1,
+  observability: { namespace: 'storage' },
+  server: ['http'],
+} as const satisfies PackageManifest;

package/src/manifest/server.ts

@@ -0,0 +1,95 @@
+/**
+ * `@12-apps/storage/manifest/server` — the server capabilities.
+ *
+ * `http.create` wraps `createApiStorage` in a WIRE VIEW that finally makes the
+ * response rendering the PACKAGE's. `StorageRouteResponse` is a three-way
+ * union — a JSON answer, an object's bytes, or a redirect to where the object
+ * lives — and until now every host turned those three arms into a `Response`
+ * itself. That is mechanism, identical for every host, and one arm of it is
+ * a security detail rather than a formatting one:
+ *
+ *     const body = response.bytes.slice().buffer;
+ *
+ * The `.slice()` is load-bearing. A `Uint8Array` from Node is a view over a
+ * POOLED allocation, so handing `.buffer` straight to `Response` serves the
+ * client whatever else happens to share that pool. A host that re-derives this
+ * renderer has to know that; a host that binds this manifest does not.
+ *
+ * The bytes and redirect arms therefore answer the contract's RAW half
+ * (`{ response }`), which wiring 1.9.0 added for exactly this: answers
+ * `{ status, body }` cannot express — a stream, a redirect whose headers are
+ * the payload, bytes with their own content type.
+ */
+
+import type { AnyServerManifest, WireRequest, WireRouteAnswer } from '@12-apps/wiring';
+
+import {
+  createApiStorage,
+  type ApiStorage,
+  type ApiStorageConfig,
+  type StorageRoute,
+  type StorageRouteResponse,
+} from '../server';
+
+/** The descriptor's chosen answer, as the wiring contract carries it. */
+export function asWireAnswer(response: StorageRouteResponse): WireRouteAnswer {
+  if ('redirect' in response) {
+    return { response: Response.redirect(response.redirect, 302) };
+  }
+  if ('bytes' in response) {
+    // Its OWN ArrayBuffer — see the note above; a view over the pool leaks.
+    const body = response.bytes.slice().buffer as ArrayBuffer;
+    return {
+      response: new Response(body, {
+        status: response.status,
+        headers: {
+          ...response.headers,
+          'content-length': String(response.bytes.byteLength),
+        },
+      }),
+    };
+  }
+  return { status: response.status, body: response.body };
+}
+
+/** One `StorageRoute` as the wiring contract reads it. */
+function asWireRoute(route: StorageRoute): {
+  method: StorageRoute['method'];
+  path: string;
+  kind: 'authenticated' | 'public';
+  handle(request: WireRequest): Promise<WireRouteAnswer>;
+} {
+  return {
+    method: route.method,
+    path: route.path,
+    // The descriptor's own `auth` flag IS the contract's route kind: a
+    // `public` object read is anonymous by design, and the host's gates read
+    // this rather than a second table that could disagree with it.
+    kind: route.auth === 'public' ? 'public' : 'authenticated',
+    handle: async (request) => {
+      if (!request.request) {
+        throw new Error('@12-apps/storage needs the raw request — bind an adapter that forwards it.');
+      }
+      return asWireAnswer(
+        await route.handle({
+          actor: (request.actor ?? null) as Parameters<StorageRoute['handle']>[0]['actor'],
+          params: request.params,
+          request: request.request,
+        }),
+      );
+    },
+  };
+}
+
+/** `createApiStorage`, its routes re-shaped for the aggregate. */
+export function createWireApiStorage(
+  config: ApiStorageConfig,
+): Omit<ApiStorage, 'routes'> & { routes: ReturnType<typeof asWireRoute>[] } {
+  const api = createApiStorage(config);
+  return { ...api, routes: api.routes.map(asWireRoute) };
+}
+
+export const storageServerManifest = {
+  name: '@12-apps/storage',
+  http: { create: createWireApiStorage },
+} as const satisfies AnyServerManifest;