@noy-db/as-aws-s3 0.2.0-pre.20

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vLannaAi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @noy-db/as-aws-s3
+
+An **`ObjectProjection`** for noy-db backed by AWS S3 — hold blob bytes as
+**native, directly-consumable S3 objects** (presigned or public) instead of
+encrypted-envelope chunks.
+
+`to-aws-s3` is the zero-knowledge **store** (ciphertext in/out). `as-aws-s3` is
+an `as-*` **projection**: raw bytes that can be served straight from S3/CDN and
+processed by AWS-native tooling. It lives **outside** the zero-knowledge
+guarantee — wiring it to a blob field is a deliberate, per-field opt-in.
+
+```ts
+import { asAwsS3 } from '@noy-db/as-aws-s3'
+
+const objects = asAwsS3({ bucket: 'acme-public-assets', region: 'eu-west-1' })
+
+await objects.putObject('logos/acme.png', bytes, { contentType: 'image/png', public: true })
+objects.publicUrl('logos/acme.png')              // stable CDN/S3 URL
+await objects.objectUrl('docs/x.pdf')            // presigned GET (time-limited)
+await objects.putUrl('videos/x.mp4', { contentType: 'video/mp4' }) // presigned PUT (direct upload)
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `bucket` | — | Target bucket (required). |
+| `prefix` | `''` | Key prefix (folder). |
+| `region` | `us-east-1` | AWS region. |
+| `client` | new client | Share a pre-built `S3Client`. |
+| `baseUrl` | virtual-hosted S3 URL | CDN origin for `publicUrl()`. |
+| `defaultExpiresInSeconds` | `900` | Presigned-URL TTL. |
+
+## Security
+
+Objects written here are **not encrypted** by noy-db. Prefer presigned
+(`objectUrl`) over public for anything sensitive, scope the bucket tightly, and
+treat public objects as **not crypto-shreddable**. See the design spec
+(`docs/superpowers/specs/2026-06-15-as-aws-s3-direct-serve-blobs-design.md`).
+
+## Peer dependencies
+
+`@noy-db/hub`, `@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`.

package/dist/index.cjs

@@ -0,0 +1,127 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  asAwsS3: () => asAwsS3
+});
+module.exports = __toCommonJS(index_exports);
+var import_client_s3 = require("@aws-sdk/client-s3");
+var import_s3_request_presigner = require("@aws-sdk/s3-request-presigner");
+function isNotFound(err) {
+  const e = err;
+  return e?.name === "NotFound" || e?.name === "NoSuchKey" || e?.$metadata?.httpStatusCode === 404;
+}
+function asAwsS3(options) {
+  const { bucket } = options;
+  const prefix = options.prefix ? options.prefix.replace(/\/+$/, "") + "/" : "";
+  const region = options.region ?? "us-east-1";
+  const client = options.client ?? new import_client_s3.S3Client({ region });
+  const presignClient = client;
+  const defaultExpiry = options.defaultExpiresInSeconds ?? 900;
+  const publicBase = (options.baseUrl ?? `https://${bucket}.s3.${region}.amazonaws.com`).replace(/\/+$/, "");
+  const fullKey = (key) => `${prefix}${key}`;
+  return {
+    name: "aws-s3",
+    async putObject(key, bytes, opts) {
+      await client.send(
+        new import_client_s3.PutObjectCommand({
+          Bucket: bucket,
+          Key: fullKey(key),
+          Body: bytes,
+          ContentType: opts.contentType,
+          ...opts.public ? { ACL: "public-read" } : {},
+          ...opts.userMeta ? { Metadata: opts.userMeta } : {}
+        })
+      );
+    },
+    async getObject(key) {
+      try {
+        const r = await client.send(new import_client_s3.GetObjectCommand({ Bucket: bucket, Key: fullKey(key) }));
+        if (!r.Body) return null;
+        return await r.Body.transformToByteArray();
+      } catch (err) {
+        if (isNotFound(err)) return null;
+        throw err;
+      }
+    },
+    async deleteObject(key) {
+      await client.send(new import_client_s3.DeleteObjectCommand({ Bucket: bucket, Key: fullKey(key) }));
+    },
+    async headObject(key) {
+      try {
+        const r = await client.send(new import_client_s3.HeadObjectCommand({ Bucket: bucket, Key: fullKey(key) }));
+        return {
+          size: r.ContentLength ?? 0,
+          ...r.ContentType ? { contentType: r.ContentType } : {},
+          ...r.ETag ? { etag: r.ETag } : {},
+          ...r.LastModified ? { lastModified: r.LastModified.toISOString() } : {},
+          ...r.Metadata && Object.keys(r.Metadata).length ? { userMeta: r.Metadata } : {}
+        };
+      } catch (err) {
+        if (isNotFound(err)) return null;
+        throw err;
+      }
+    },
+    async objectUrl(key, opts) {
+      return await (0, import_s3_request_presigner.getSignedUrl)(presignClient, new import_client_s3.GetObjectCommand({ Bucket: bucket, Key: fullKey(key) }), {
+        expiresIn: opts?.expiresInSeconds ?? defaultExpiry
+      });
+    },
+    async putUrl(key, opts) {
+      return await (0, import_s3_request_presigner.getSignedUrl)(
+        presignClient,
+        new import_client_s3.PutObjectCommand({ Bucket: bucket, Key: fullKey(key), ContentType: opts.contentType }),
+        { expiresIn: opts.expiresInSeconds ?? defaultExpiry }
+      );
+    },
+    async listPrefix(listPrefixArg) {
+      const out = [];
+      let token;
+      do {
+        const r = await client.send(
+          new import_client_s3.ListObjectsV2Command({ Bucket: bucket, Prefix: fullKey(listPrefixArg), ContinuationToken: token })
+        );
+        for (const obj of r.Contents ?? []) {
+          if (!obj.Key) continue;
+          const logicalKey = prefix && obj.Key.startsWith(prefix) ? obj.Key.slice(prefix.length) : obj.Key;
+          out.push({
+            key: logicalKey,
+            meta: {
+              size: obj.Size ?? 0,
+              ...obj.ETag ? { etag: obj.ETag } : {},
+              ...obj.LastModified ? { lastModified: obj.LastModified.toISOString() } : {}
+            }
+          });
+        }
+        token = r.IsTruncated ? r.NextContinuationToken : void 0;
+      } while (token);
+      return out;
+    },
+    publicUrl(key) {
+      return `${publicBase}/${fullKey(key)}`;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  asAwsS3
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@noy-db/as-aws-s3` — an {@link ObjectProjection} backed by AWS S3.\n *\n * Where `@noy-db/to-aws-s3` is a `to-*` store (ciphertext envelopes in/out, the\n * zero-knowledge backend), this is an `as-*` **projection**: it holds blob bytes\n * as **native, directly-consumable S3 objects** so they can be served straight\n * from S3/CDN — presigned (time-limited, private) or public — and processed by\n * AWS-native tooling. It sees **raw bytes** and lives **outside** the\n * zero-knowledge guarantee; wiring it to a blob field is a deliberate opt-in.\n *\n * @example\n * ```ts\n * import { asAwsS3 } from '@noy-db/as-aws-s3'\n * const objects = asAwsS3({ bucket: 'acme-public-assets', region: 'eu-west-1' })\n * await objects.putObject('logos/acme.png', bytes, { contentType: 'image/png', public: true })\n * const url = objects.publicUrl('logos/acme.png')          // stable CDN/S3 URL\n * const dl  = await objects.objectUrl('logos/acme.png')    // presigned GET\n * const up  = await objects.putUrl('videos/x.mp4', { contentType: 'video/mp4' }) // presigned PUT\n * ```\n */\nimport type {\n  ObjectProjection,\n  ObjectMeta,\n  PutObjectOptions,\n  ObjectUrlOptions,\n  PutUrlOptions,\n} from '@noy-db/hub'\nimport {\n  S3Client,\n  PutObjectCommand,\n  GetObjectCommand,\n  DeleteObjectCommand,\n  HeadObjectCommand,\n  ListObjectsV2Command,\n} from '@aws-sdk/client-s3'\nimport { getSignedUrl } from '@aws-sdk/s3-request-presigner'\n\nexport interface AsAwsS3Options {\n  /** Target bucket. */\n  bucket: string\n  /** Key prefix (folder). A trailing slash is added if missing. */\n  prefix?: string\n  /** AWS region. Default `us-east-1`. */\n  region?: string\n  /** Pre-built `S3Client` to share (overrides `region`). */\n  client?: S3Client\n  /**\n   * Base URL for `publicUrl()` — a CDN origin or the bucket's website/vhost\n   * URL. Defaults to the virtual-hosted S3 URL\n   * (`https://{bucket}.s3.{region}.amazonaws.com`).\n   */\n  baseUrl?: string\n  /** Default presigned-URL TTL (seconds). Default 900 (15 min). */\n  defaultExpiresInSeconds?: number\n}\n\n/** The projection plus an S3-specific stable-public-URL helper. */\nexport type AsAwsS3Projection = ObjectProjection & {\n  /** A stable, non-expiring URL for a **public** object (CDN/vhost). */\n  publicUrl(key: string): string\n}\n\nfunction isNotFound(err: unknown): boolean {\n  const e = err as { name?: string; $metadata?: { httpStatusCode?: number } }\n  return e?.name === 'NotFound' || e?.name === 'NoSuchKey' || e?.$metadata?.httpStatusCode === 404\n}\n\nexport function asAwsS3(options: AsAwsS3Options): AsAwsS3Projection {\n  const { bucket } = options\n  const prefix = options.prefix ? options.prefix.replace(/\\/+$/, '') + '/' : ''\n  const region = options.region ?? 'us-east-1'\n  const client = options.client ?? new S3Client({ region })\n  // getSignedUrl types its client against its own @smithy/types copy; when the\n  // installed @aws-sdk/client-s3 and s3-request-presigner resolve to different\n  // minor versions, S3Client and the expected Client diverge only on a private\n  // `handlers` field. Runtime is identical — cast across the version skew.\n  const presignClient = client as unknown as Parameters<typeof getSignedUrl>[0]\n  const defaultExpiry = options.defaultExpiresInSeconds ?? 900\n  const publicBase = (options.baseUrl ?? `https://${bucket}.s3.${region}.amazonaws.com`).replace(/\\/+$/, '')\n  const fullKey = (key: string): string => `${prefix}${key}`\n\n  return {\n    name: 'aws-s3',\n\n    async putObject(key: string, bytes: Uint8Array, opts: PutObjectOptions): Promise<void> {\n      await client.send(\n        new PutObjectCommand({\n          Bucket: bucket,\n          Key: fullKey(key),\n          Body: bytes,\n          ContentType: opts.contentType,\n          ...(opts.public ? { ACL: 'public-read' as const } : {}),\n          ...(opts.userMeta ? { Metadata: opts.userMeta } : {}),\n        }),\n      )\n    },\n\n    async getObject(key: string): Promise<Uint8Array | null> {\n      try {\n        const r = await client.send(new GetObjectCommand({ Bucket: bucket, Key: fullKey(key) }))\n        if (!r.Body) return null\n        return await r.Body.transformToByteArray()\n      } catch (err) {\n        if (isNotFound(err)) return null\n        throw err\n      }\n    },\n\n    async deleteObject(key: string): Promise<void> {\n      await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: fullKey(key) }))\n    },\n\n    async headObject(key: string): Promise<ObjectMeta | null> {\n      try {\n        const r = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: fullKey(key) }))\n        return {\n          size: r.ContentLength ?? 0,\n          ...(r.ContentType ? { contentType: r.ContentType } : {}),\n          ...(r.ETag ? { etag: r.ETag } : {}),\n          ...(r.LastModified ? { lastModified: r.LastModified.toISOString() } : {}),\n          ...(r.Metadata && Object.keys(r.Metadata).length ? { userMeta: r.Metadata } : {}),\n        }\n      } catch (err) {\n        if (isNotFound(err)) return null\n        throw err\n      }\n    },\n\n    async objectUrl(key: string, opts?: ObjectUrlOptions): Promise<string> {\n      // Always a presigned GET — works for private and public objects alike.\n      // For a stable public URL, use `publicUrl()`.\n      return await getSignedUrl(presignClient, new GetObjectCommand({ Bucket: bucket, Key: fullKey(key) }), {\n        expiresIn: opts?.expiresInSeconds ?? defaultExpiry,\n      })\n    },\n\n    async putUrl(key: string, opts: PutUrlOptions): Promise<string> {\n      return await getSignedUrl(\n        presignClient,\n        new PutObjectCommand({ Bucket: bucket, Key: fullKey(key), ContentType: opts.contentType }),\n        { expiresIn: opts.expiresInSeconds ?? defaultExpiry },\n      )\n    },\n\n    async listPrefix(listPrefixArg: string) {\n      const out: Array<{ key: string; meta: ObjectMeta }> = []\n      let token: string | undefined\n      do {\n        const r = await client.send(\n          new ListObjectsV2Command({ Bucket: bucket, Prefix: fullKey(listPrefixArg), ContinuationToken: token }),\n        )\n        for (const obj of r.Contents ?? []) {\n          if (!obj.Key) continue\n          // Strip the configured prefix so callers see logical keys.\n          const logicalKey = prefix && obj.Key.startsWith(prefix) ? obj.Key.slice(prefix.length) : obj.Key\n          out.push({\n            key: logicalKey,\n            meta: {\n              size: obj.Size ?? 0,\n              ...(obj.ETag ? { etag: obj.ETag } : {}),\n              ...(obj.LastModified ? { lastModified: obj.LastModified.toISOString() } : {}),\n            },\n          })\n        }\n        token = r.IsTruncated ? r.NextContinuationToken : undefined\n      } while (token)\n      return out\n    },\n\n    publicUrl(key: string): string {\n      return `${publicBase}/${fullKey(key)}`\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,50 @@
+import { ObjectProjection } from '@noy-db/hub';
+import { S3Client } from '@aws-sdk/client-s3';
+
+/**
+ * `@noy-db/as-aws-s3` — an {@link ObjectProjection} backed by AWS S3.
+ *
+ * Where `@noy-db/to-aws-s3` is a `to-*` store (ciphertext envelopes in/out, the
+ * zero-knowledge backend), this is an `as-*` **projection**: it holds blob bytes
+ * as **native, directly-consumable S3 objects** so they can be served straight
+ * from S3/CDN — presigned (time-limited, private) or public — and processed by
+ * AWS-native tooling. It sees **raw bytes** and lives **outside** the
+ * zero-knowledge guarantee; wiring it to a blob field is a deliberate opt-in.
+ *
+ * @example
+ * ```ts
+ * import { asAwsS3 } from '@noy-db/as-aws-s3'
+ * const objects = asAwsS3({ bucket: 'acme-public-assets', region: 'eu-west-1' })
+ * await objects.putObject('logos/acme.png', bytes, { contentType: 'image/png', public: true })
+ * const url = objects.publicUrl('logos/acme.png')          // stable CDN/S3 URL
+ * const dl  = await objects.objectUrl('logos/acme.png')    // presigned GET
+ * const up  = await objects.putUrl('videos/x.mp4', { contentType: 'video/mp4' }) // presigned PUT
+ * ```
+ */
+
+interface AsAwsS3Options {
+    /** Target bucket. */
+    bucket: string;
+    /** Key prefix (folder). A trailing slash is added if missing. */
+    prefix?: string;
+    /** AWS region. Default `us-east-1`. */
+    region?: string;
+    /** Pre-built `S3Client` to share (overrides `region`). */
+    client?: S3Client;
+    /**
+     * Base URL for `publicUrl()` — a CDN origin or the bucket's website/vhost
+     * URL. Defaults to the virtual-hosted S3 URL
+     * (`https://{bucket}.s3.{region}.amazonaws.com`).
+     */
+    baseUrl?: string;
+    /** Default presigned-URL TTL (seconds). Default 900 (15 min). */
+    defaultExpiresInSeconds?: number;
+}
+/** The projection plus an S3-specific stable-public-URL helper. */
+type AsAwsS3Projection = ObjectProjection & {
+    /** A stable, non-expiring URL for a **public** object (CDN/vhost). */
+    publicUrl(key: string): string;
+};
+declare function asAwsS3(options: AsAwsS3Options): AsAwsS3Projection;
+
+export { type AsAwsS3Options, type AsAwsS3Projection, asAwsS3 };

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import { ObjectProjection } from '@noy-db/hub';
+import { S3Client } from '@aws-sdk/client-s3';
+
+/**
+ * `@noy-db/as-aws-s3` — an {@link ObjectProjection} backed by AWS S3.
+ *
+ * Where `@noy-db/to-aws-s3` is a `to-*` store (ciphertext envelopes in/out, the
+ * zero-knowledge backend), this is an `as-*` **projection**: it holds blob bytes
+ * as **native, directly-consumable S3 objects** so they can be served straight
+ * from S3/CDN — presigned (time-limited, private) or public — and processed by
+ * AWS-native tooling. It sees **raw bytes** and lives **outside** the
+ * zero-knowledge guarantee; wiring it to a blob field is a deliberate opt-in.
+ *
+ * @example
+ * ```ts
+ * import { asAwsS3 } from '@noy-db/as-aws-s3'
+ * const objects = asAwsS3({ bucket: 'acme-public-assets', region: 'eu-west-1' })
+ * await objects.putObject('logos/acme.png', bytes, { contentType: 'image/png', public: true })
+ * const url = objects.publicUrl('logos/acme.png')          // stable CDN/S3 URL
+ * const dl  = await objects.objectUrl('logos/acme.png')    // presigned GET
+ * const up  = await objects.putUrl('videos/x.mp4', { contentType: 'video/mp4' }) // presigned PUT
+ * ```
+ */
+
+interface AsAwsS3Options {
+    /** Target bucket. */
+    bucket: string;
+    /** Key prefix (folder). A trailing slash is added if missing. */
+    prefix?: string;
+    /** AWS region. Default `us-east-1`. */
+    region?: string;
+    /** Pre-built `S3Client` to share (overrides `region`). */
+    client?: S3Client;
+    /**
+     * Base URL for `publicUrl()` — a CDN origin or the bucket's website/vhost
+     * URL. Defaults to the virtual-hosted S3 URL
+     * (`https://{bucket}.s3.{region}.amazonaws.com`).
+     */
+    baseUrl?: string;
+    /** Default presigned-URL TTL (seconds). Default 900 (15 min). */
+    defaultExpiresInSeconds?: number;
+}
+/** The projection plus an S3-specific stable-public-URL helper. */
+type AsAwsS3Projection = ObjectProjection & {
+    /** A stable, non-expiring URL for a **public** object (CDN/vhost). */
+    publicUrl(key: string): string;
+};
+declare function asAwsS3(options: AsAwsS3Options): AsAwsS3Projection;
+
+export { type AsAwsS3Options, type AsAwsS3Projection, asAwsS3 };

package/dist/index.js

@@ -0,0 +1,109 @@
+// src/index.ts
+import {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+  DeleteObjectCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+function isNotFound(err) {
+  const e = err;
+  return e?.name === "NotFound" || e?.name === "NoSuchKey" || e?.$metadata?.httpStatusCode === 404;
+}
+function asAwsS3(options) {
+  const { bucket } = options;
+  const prefix = options.prefix ? options.prefix.replace(/\/+$/, "") + "/" : "";
+  const region = options.region ?? "us-east-1";
+  const client = options.client ?? new S3Client({ region });
+  const presignClient = client;
+  const defaultExpiry = options.defaultExpiresInSeconds ?? 900;
+  const publicBase = (options.baseUrl ?? `https://${bucket}.s3.${region}.amazonaws.com`).replace(/\/+$/, "");
+  const fullKey = (key) => `${prefix}${key}`;
+  return {
+    name: "aws-s3",
+    async putObject(key, bytes, opts) {
+      await client.send(
+        new PutObjectCommand({
+          Bucket: bucket,
+          Key: fullKey(key),
+          Body: bytes,
+          ContentType: opts.contentType,
+          ...opts.public ? { ACL: "public-read" } : {},
+          ...opts.userMeta ? { Metadata: opts.userMeta } : {}
+        })
+      );
+    },
+    async getObject(key) {
+      try {
+        const r = await client.send(new GetObjectCommand({ Bucket: bucket, Key: fullKey(key) }));
+        if (!r.Body) return null;
+        return await r.Body.transformToByteArray();
+      } catch (err) {
+        if (isNotFound(err)) return null;
+        throw err;
+      }
+    },
+    async deleteObject(key) {
+      await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: fullKey(key) }));
+    },
+    async headObject(key) {
+      try {
+        const r = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: fullKey(key) }));
+        return {
+          size: r.ContentLength ?? 0,
+          ...r.ContentType ? { contentType: r.ContentType } : {},
+          ...r.ETag ? { etag: r.ETag } : {},
+          ...r.LastModified ? { lastModified: r.LastModified.toISOString() } : {},
+          ...r.Metadata && Object.keys(r.Metadata).length ? { userMeta: r.Metadata } : {}
+        };
+      } catch (err) {
+        if (isNotFound(err)) return null;
+        throw err;
+      }
+    },
+    async objectUrl(key, opts) {
+      return await getSignedUrl(presignClient, new GetObjectCommand({ Bucket: bucket, Key: fullKey(key) }), {
+        expiresIn: opts?.expiresInSeconds ?? defaultExpiry
+      });
+    },
+    async putUrl(key, opts) {
+      return await getSignedUrl(
+        presignClient,
+        new PutObjectCommand({ Bucket: bucket, Key: fullKey(key), ContentType: opts.contentType }),
+        { expiresIn: opts.expiresInSeconds ?? defaultExpiry }
+      );
+    },
+    async listPrefix(listPrefixArg) {
+      const out = [];
+      let token;
+      do {
+        const r = await client.send(
+          new ListObjectsV2Command({ Bucket: bucket, Prefix: fullKey(listPrefixArg), ContinuationToken: token })
+        );
+        for (const obj of r.Contents ?? []) {
+          if (!obj.Key) continue;
+          const logicalKey = prefix && obj.Key.startsWith(prefix) ? obj.Key.slice(prefix.length) : obj.Key;
+          out.push({
+            key: logicalKey,
+            meta: {
+              size: obj.Size ?? 0,
+              ...obj.ETag ? { etag: obj.ETag } : {},
+              ...obj.LastModified ? { lastModified: obj.LastModified.toISOString() } : {}
+            }
+          });
+        }
+        token = r.IsTruncated ? r.NextContinuationToken : void 0;
+      } while (token);
+      return out;
+    },
+    publicUrl(key) {
+      return `${publicBase}/${fullKey(key)}`;
+    }
+  };
+}
+export {
+  asAwsS3
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@noy-db/as-aws-s3` — an {@link ObjectProjection} backed by AWS S3.\n *\n * Where `@noy-db/to-aws-s3` is a `to-*` store (ciphertext envelopes in/out, the\n * zero-knowledge backend), this is an `as-*` **projection**: it holds blob bytes\n * as **native, directly-consumable S3 objects** so they can be served straight\n * from S3/CDN — presigned (time-limited, private) or public — and processed by\n * AWS-native tooling. It sees **raw bytes** and lives **outside** the\n * zero-knowledge guarantee; wiring it to a blob field is a deliberate opt-in.\n *\n * @example\n * ```ts\n * import { asAwsS3 } from '@noy-db/as-aws-s3'\n * const objects = asAwsS3({ bucket: 'acme-public-assets', region: 'eu-west-1' })\n * await objects.putObject('logos/acme.png', bytes, { contentType: 'image/png', public: true })\n * const url = objects.publicUrl('logos/acme.png')          // stable CDN/S3 URL\n * const dl  = await objects.objectUrl('logos/acme.png')    // presigned GET\n * const up  = await objects.putUrl('videos/x.mp4', { contentType: 'video/mp4' }) // presigned PUT\n * ```\n */\nimport type {\n  ObjectProjection,\n  ObjectMeta,\n  PutObjectOptions,\n  ObjectUrlOptions,\n  PutUrlOptions,\n} from '@noy-db/hub'\nimport {\n  S3Client,\n  PutObjectCommand,\n  GetObjectCommand,\n  DeleteObjectCommand,\n  HeadObjectCommand,\n  ListObjectsV2Command,\n} from '@aws-sdk/client-s3'\nimport { getSignedUrl } from '@aws-sdk/s3-request-presigner'\n\nexport interface AsAwsS3Options {\n  /** Target bucket. */\n  bucket: string\n  /** Key prefix (folder). A trailing slash is added if missing. */\n  prefix?: string\n  /** AWS region. Default `us-east-1`. */\n  region?: string\n  /** Pre-built `S3Client` to share (overrides `region`). */\n  client?: S3Client\n  /**\n   * Base URL for `publicUrl()` — a CDN origin or the bucket's website/vhost\n   * URL. Defaults to the virtual-hosted S3 URL\n   * (`https://{bucket}.s3.{region}.amazonaws.com`).\n   */\n  baseUrl?: string\n  /** Default presigned-URL TTL (seconds). Default 900 (15 min). */\n  defaultExpiresInSeconds?: number\n}\n\n/** The projection plus an S3-specific stable-public-URL helper. */\nexport type AsAwsS3Projection = ObjectProjection & {\n  /** A stable, non-expiring URL for a **public** object (CDN/vhost). */\n  publicUrl(key: string): string\n}\n\nfunction isNotFound(err: unknown): boolean {\n  const e = err as { name?: string; $metadata?: { httpStatusCode?: number } }\n  return e?.name === 'NotFound' || e?.name === 'NoSuchKey' || e?.$metadata?.httpStatusCode === 404\n}\n\nexport function asAwsS3(options: AsAwsS3Options): AsAwsS3Projection {\n  const { bucket } = options\n  const prefix = options.prefix ? options.prefix.replace(/\\/+$/, '') + '/' : ''\n  const region = options.region ?? 'us-east-1'\n  const client = options.client ?? new S3Client({ region })\n  // getSignedUrl types its client against its own @smithy/types copy; when the\n  // installed @aws-sdk/client-s3 and s3-request-presigner resolve to different\n  // minor versions, S3Client and the expected Client diverge only on a private\n  // `handlers` field. Runtime is identical — cast across the version skew.\n  const presignClient = client as unknown as Parameters<typeof getSignedUrl>[0]\n  const defaultExpiry = options.defaultExpiresInSeconds ?? 900\n  const publicBase = (options.baseUrl ?? `https://${bucket}.s3.${region}.amazonaws.com`).replace(/\\/+$/, '')\n  const fullKey = (key: string): string => `${prefix}${key}`\n\n  return {\n    name: 'aws-s3',\n\n    async putObject(key: string, bytes: Uint8Array, opts: PutObjectOptions): Promise<void> {\n      await client.send(\n        new PutObjectCommand({\n          Bucket: bucket,\n          Key: fullKey(key),\n          Body: bytes,\n          ContentType: opts.contentType,\n          ...(opts.public ? { ACL: 'public-read' as const } : {}),\n          ...(opts.userMeta ? { Metadata: opts.userMeta } : {}),\n        }),\n      )\n    },\n\n    async getObject(key: string): Promise<Uint8Array | null> {\n      try {\n        const r = await client.send(new GetObjectCommand({ Bucket: bucket, Key: fullKey(key) }))\n        if (!r.Body) return null\n        return await r.Body.transformToByteArray()\n      } catch (err) {\n        if (isNotFound(err)) return null\n        throw err\n      }\n    },\n\n    async deleteObject(key: string): Promise<void> {\n      await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: fullKey(key) }))\n    },\n\n    async headObject(key: string): Promise<ObjectMeta | null> {\n      try {\n        const r = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: fullKey(key) }))\n        return {\n          size: r.ContentLength ?? 0,\n          ...(r.ContentType ? { contentType: r.ContentType } : {}),\n          ...(r.ETag ? { etag: r.ETag } : {}),\n          ...(r.LastModified ? { lastModified: r.LastModified.toISOString() } : {}),\n          ...(r.Metadata && Object.keys(r.Metadata).length ? { userMeta: r.Metadata } : {}),\n        }\n      } catch (err) {\n        if (isNotFound(err)) return null\n        throw err\n      }\n    },\n\n    async objectUrl(key: string, opts?: ObjectUrlOptions): Promise<string> {\n      // Always a presigned GET — works for private and public objects alike.\n      // For a stable public URL, use `publicUrl()`.\n      return await getSignedUrl(presignClient, new GetObjectCommand({ Bucket: bucket, Key: fullKey(key) }), {\n        expiresIn: opts?.expiresInSeconds ?? defaultExpiry,\n      })\n    },\n\n    async putUrl(key: string, opts: PutUrlOptions): Promise<string> {\n      return await getSignedUrl(\n        presignClient,\n        new PutObjectCommand({ Bucket: bucket, Key: fullKey(key), ContentType: opts.contentType }),\n        { expiresIn: opts.expiresInSeconds ?? defaultExpiry },\n      )\n    },\n\n    async listPrefix(listPrefixArg: string) {\n      const out: Array<{ key: string; meta: ObjectMeta }> = []\n      let token: string | undefined\n      do {\n        const r = await client.send(\n          new ListObjectsV2Command({ Bucket: bucket, Prefix: fullKey(listPrefixArg), ContinuationToken: token }),\n        )\n        for (const obj of r.Contents ?? []) {\n          if (!obj.Key) continue\n          // Strip the configured prefix so callers see logical keys.\n          const logicalKey = prefix && obj.Key.startsWith(prefix) ? obj.Key.slice(prefix.length) : obj.Key\n          out.push({\n            key: logicalKey,\n            meta: {\n              size: obj.Size ?? 0,\n              ...(obj.ETag ? { etag: obj.ETag } : {}),\n              ...(obj.LastModified ? { lastModified: obj.LastModified.toISOString() } : {}),\n            },\n          })\n        }\n        token = r.IsTruncated ? r.NextContinuationToken : undefined\n      } while (token)\n      return out\n    },\n\n    publicUrl(key: string): string {\n      return `${publicBase}/${fullKey(key)}`\n    },\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@noy-db/as-aws-s3",
+  "version": "0.2.0-pre.20",
+  "description": "AWS S3 object projection for noy-db — serve blob bytes directly from S3/CDN (presigned or public), outside the encrypted store",
+  "license": "MIT",
+  "author": "vLannaAi <vicio@lanna.ai>",
+  "homepage": "https://github.com/vLannaAi/noy-db/tree/main/packages/as-aws-s3#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vLannaAi/noy-db.git",
+    "directory": "packages/as-aws-s3"
+  },
+  "bugs": {
+    "url": "https://github.com/vLannaAi/noy-db/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/s3-request-presigner": "^3.0.0",
+    "@noy-db/hub": "0.2.0-pre.20"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/s3-request-presigner": "^3.0.0",
+    "@noy-db/hub": "0.2.0-pre.20"
+  },
+  "keywords": [
+    "noy-db",
+    "projection",
+    "s3",
+    "aws",
+    "object-storage",
+    "presigned-url",
+    "cdn",
+    "direct-serve"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  }
+}