@venizia/ignis 0.2.0-23 → 0.2.0-24

package/dist/components/static-asset/index.d.ts

@@ -3,4 +3,5 @@ export * from './component';
 export * from './controller';
 export * from './models';
 export * from './repositories';
+export * from './ingest';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/static-asset/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/static-asset/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/static-asset/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC"}

package/dist/components/static-asset/index.js

@@ -19,4 +19,5 @@ __exportStar(require("./component"), exports);
 __exportStar(require("./controller"), exports);
 __exportStar(require("./models"), exports);
 __exportStar(require("./repositories"), exports);
+__exportStar(require("./ingest"), exports);
 //# sourceMappingURL=index.js.map

package/dist/components/static-asset/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/static-asset/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,8CAA4B;AAC5B,+CAA6B;AAC7B,2CAAyB;AACzB,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/static-asset/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,8CAA4B;AAC5B,+CAA6B;AAC7B,2CAAyB;AACzB,iDAA+B;AAC/B,2CAAyB"}

package/dist/components/static-asset/ingest.d.ts

@@ -0,0 +1,58 @@
+import { type IBucketRef, type IObjectRef, type IFileStat, type IStorageHelper, type IUploadResult, type IUrlSafetyPolicy } from '@venizia/ignis-helpers';
+/**
+ * What was stored, and what the backend reports about it. The stat is returned because `getStat`
+ * already ran to size the result - a caller writing its own row would otherwise pay for it twice.
+ *
+ * This does NOT write a meta link. The columns an application attaches to an object - a principal,
+ * a variant - come from its own domain, not from the object, so the row stays the caller's.
+ */
+export interface IIngestFromUrlResult {
+    upload: IUploadResult;
+    stat: IFileStat;
+}
+/** Where a fetched object lands, and what it is attached to. */
+export interface IIngestFromUrlOptions {
+    helper: IStorageHelper;
+    url: string;
+    bucket: IBucketRef;
+    /**
+     * Decides the stored key.
+     *
+     * **Absent, the key comes from the remote url's last path segment - which on an untrusted url is
+     * named by whoever supplied it.** Pass `resolveKey` whenever the url is not your own; the
+     * validation below bounds what it can do, but it does not make the remote name yours.
+     */
+    resolveKey?: (opts: {
+        url: URL;
+        contentType: string;
+    }) => string;
+    folderPath?: string;
+    /** Absent leaves IGNIS's own default: https only, no private address, 3 hops, 10s, 10 MB. */
+    policy?: IUrlSafetyPolicy;
+    /** Folder nesting the key may carry. Absent uses `BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH`. */
+    maxFolderDepth?: number;
+    /**
+     * Where the object is served from. **Required**: an absent hook used to yield an empty link, which
+     * is exactly the value that satisfies a NOT NULL column and points nowhere.
+     */
+    normalizeLinkFn: (opts: {
+        bucket: IBucketRef;
+        object: IObjectRef;
+    }) => string;
+}
+/** Storing an object that came from somewhere else. */
+export declare class AssetIngest {
+    /**
+     * Fetches an untrusted url and stores what comes back, without the bytes passing through this
+     * process: the guarded body is capped and handed to `writeStream` as a stream.
+     *
+     * The url is guarded by `UrlIngest.fetchGuarded` - scheme allow-list, every resolved address
+     * checked, redirects walked by hand with a per-hop re-check, and a timeout. A rebinding window
+     * remains open between the check and the connect; see `UrlIngest.assertPublicHost`.
+     *
+     * The served content type is decided from the stored KEY, never from what the remote host
+     * claimed - the same rule the asset routes apply, and for the same reason.
+     */
+    static fromUrl(opts: IIngestFromUrlOptions): Promise<IIngestFromUrlResult>;
+}
+//# sourceMappingURL=ingest.d.ts.map

package/dist/components/static-asset/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../../src/components/static-asset/ingest.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,cAAc,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,UAAU,CAAC;IAEnB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,GAAG,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAE1B,kGAAkG;IAClG,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,eAAe,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,KAAK,MAAM,CAAC;CAC/E;AAUD,uDAAuD;AACvD,qBAAa,WAAW;IACtB;;;;;;;;;;OAUG;WACU,OAAO,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAkEjF"}

package/dist/components/static-asset/ingest.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssetIngest = void 0;
+const core_1 = require("@venizia/ignis-helpers/core");
+const ignis_helpers_1 = require("@venizia/ignis-helpers");
+const readKeyFromUrl = (opts) => {
+    const { url, folderPath } = opts;
+    const lastSegment = url.pathname.split('/').filter(Boolean).pop() ?? 'object';
+    const normalized = lastSegment.toLowerCase().replace(/ /g, '_');
+    return folderPath ? `${folderPath}/${normalized}` : normalized;
+};
+/** Storing an object that came from somewhere else. */
+class AssetIngest {
+    /**
+     * Fetches an untrusted url and stores what comes back, without the bytes passing through this
+     * process: the guarded body is capped and handed to `writeStream` as a stream.
+     *
+     * The url is guarded by `UrlIngest.fetchGuarded` - scheme allow-list, every resolved address
+     * checked, redirects walked by hand with a per-hop re-check, and a timeout. A rebinding window
+     * remains open between the check and the connect; see `UrlIngest.assertPublicHost`.
+     *
+     * The served content type is decided from the stored KEY, never from what the remote host
+     * claimed - the same rule the asset routes apply, and for the same reason.
+     */
+    static async fromUrl(opts) {
+        const { helper, url, bucket, folderPath, policy, resolveKey, normalizeLinkFn } = opts;
+        const response = await ignis_helpers_1.UrlIngest.fetchGuarded({ url, policy });
+        const remoteType = response.headers.get('content-type')?.split(';')[0]?.trim() ?? '';
+        const parsed = new URL(url);
+        const key = resolveKey
+            ? resolveKey({ url: parsed, contentType: remoteType })
+            : readKeyFromUrl({ url: parsed, folderPath });
+        // The helper's own default, not an unbounded one: an object arriving through ingest must obey
+        // the same depth rule as one arriving through the upload route.
+        if (!helper.isValidObjectKey({ object: { key }, maxDepth: opts.maxFolderDepth })) {
+            await response.body?.cancel();
+            throw (0, core_1.getError)({ message: `[AssetIngest.fromUrl] Invalid object key | key: ${key}` });
+        }
+        // Refused BEFORE the write starts, so a body that declares its size never opens a multipart
+        // upload at all. A body that lies or omits the header is caught mid-flight by `capStream`, and
+        // Bun's client answers that with `AbortMultipartUpload` - measured against a recording endpoint,
+        // not assumed - so no orphaned parts are left behind either way.
+        const declaredLength = Number(response.headers.get('content-length') ?? 0);
+        const maxBytes = policy?.maxBytes ?? ignis_helpers_1.UrlSafetyDefaults.MAX_BYTES;
+        if (declaredLength > maxBytes) {
+            await response.body?.cancel();
+            throw (0, core_1.getError)({
+                error: ignis_helpers_1.UrlSafetyErrors.URL_REFUSED,
+                message: `[AssetIngest.fromUrl] Body exceeds the cap | declared: ${declaredLength} | max: ${maxBytes}`,
+            });
+        }
+        if (!response.body) {
+            throw (0, core_1.getError)({ message: `[AssetIngest.fromUrl] Response carried no body | url: ${url}` });
+        }
+        const object = { key };
+        const contentType = helper.getMimeType({ filename: key });
+        await helper.writeStream({
+            bucket,
+            object,
+            source: ignis_helpers_1.UrlIngest.capStream({ source: response.body, policy }),
+            contentType,
+            maxFolderDepth: opts.maxFolderDepth,
+        });
+        const stat = await helper.getStat({ bucket, object });
+        const link = normalizeLinkFn({ bucket, object });
+        if (!link) {
+            throw (0, core_1.getError)({
+                message: `[AssetIngest.fromUrl] normalizeLinkFn returned an empty link | key: ${key}`,
+            });
+        }
+        return {
+            upload: {
+                bucket: { name: bucket.name },
+                object: { key, size: stat.size, contentType },
+                link,
+            },
+            stat,
+        };
+    }
+}
+exports.AssetIngest = AssetIngest;
+//# sourceMappingURL=ingest.js.map

package/dist/components/static-asset/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../../src/components/static-asset/ingest.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venizia/ignis",
-  "version": "0.2.0-23",
+  "version": "0.2.0-24",
   "description": "High-performance TypeScript server infrastructure combining LoopBack 4 enterprise architecture (decorator-based DI, repository pattern, component system) with Hono speed (~140k req/s). Features auto-generated OpenAPI docs, Drizzle ORM type-safe SQL, JWT/Basic authentication, Casbin authorization, convention-based bootstrapping, and pluggable components for health checks, Swagger UI, mail, Socket.IO, and static assets. Built for Bun and Node.js.",
   "keywords": [
     "access-control",
@@ -200,7 +200,7 @@
   "dependencies": {
     "@venizia/ignis-connectors": "^0.2.0-23",
     "@venizia/ignis-filter": "^0.2.0-7",
-    "@venizia/ignis-helpers": "^0.2.0-17",
+    "@venizia/ignis-helpers": "^0.2.0-18",
     "@venizia/ignis-inversion": "^0.2.0-5",
     "@venizia/ignis-kernel": "^0.2.0-23",
     "lodash": "^4.18.1",