@absolutejs/audit-s3 0.0.1

package/README.md

@@ -0,0 +1,162 @@
+# @absolutejs/audit-s3
+
+S3-compatible `AuditSink` for [@absolutejs/audit](https://github.com/absolutejs/audit).
+
+Buffered JSONL writes to AWS S3 / Cloudflare R2 / Backblaze B2 / MinIO — any
+store with a "put a string at a key" API.
+
+## Why S3 for audit logs
+
+- **WORM (write-once-read-many) buckets** give legal hold for compliance
+  retention (SOC2, HIPAA, FedRAMP). The hash-chain in
+  `@absolutejs/audit`'s `withIntegrity()` gives tamper-evidence; WORM
+  prevents deletion even by an admin.
+- **Lifecycle policies** handle retention windows without a cron job.
+  "Move to Glacier after 90 days, delete after 7 years" is one bucket
+  policy.
+- **Cheap.** Cold-tier storage costs cents/GB-month.
+- **Queryable later** via Athena, DuckDB, or `s3 ls | xargs cat`.
+
+S3 objects are immutable, so the sink buffers events and flushes as JSONL
+files keyed by time. Object keys are lexically sortable; `s3 ls audit/`
+returns events in chronological order.
+
+## Install
+
+```sh
+bun add @absolutejs/audit @absolutejs/audit-s3
+# Bring whichever S3 client you already use — no SDK lock-in:
+bun add @aws-sdk/client-s3      # OR
+# (Cloudflare R2 Workers binding — no install)
+```
+
+## Usage
+
+### AWS SDK v3
+
+```ts
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { createAudit, withIntegrity, memorySink } from '@absolutejs/audit';
+import { createS3AuditSink } from '@absolutejs/audit-s3';
+
+const s3 = new S3Client({ region: 'us-east-1' });
+
+const audit = createAudit({
+  sinks: [
+    memorySink({ max: 1000 }),                          // hot tail for queries
+    withIntegrity(                                       // tamper-evident
+      createS3AuditSink({
+        put: async (key, body, contentType) => {
+          await s3.send(new PutObjectCommand({
+            Bucket: 'my-audit-bucket',
+            Key: key,
+            Body: body,
+            ContentType: contentType,
+          }));
+        },
+        prefix: 'audit/prod/',
+        flushIntervalMs: 5_000,
+      }),
+      { secret: process.env.AUDIT_SECRET, writerId: 'shard-A' }
+    ),
+  ],
+});
+
+await audit.append({
+  kind: 'auth.login',
+  actor: 'user-123',
+  metadata: { ip: '10.0.0.1' },
+});
+
+// On graceful shutdown:
+await audit.close();
+```
+
+### Cloudflare R2 (Workers)
+
+```ts
+import { createS3AuditSink } from '@absolutejs/audit-s3';
+
+const sink = createS3AuditSink({
+  put: async (key, body, contentType) => {
+    await env.AUDIT_BUCKET.put(key, body, { httpMetadata: { contentType } });
+  },
+});
+```
+
+### MinIO
+
+Same as AWS SDK — MinIO speaks S3 protocol. Point the `S3Client` at your
+MinIO endpoint and the adapter doesn't care.
+
+## Object key layout
+
+Default `keyFor` produces:
+
+```
+audit/2026-05-30/19-42-15.123-abcd1234.jsonl
+```
+
+- **Date prefix** (`2026-05-30/`) — lifecycle policies key off this.
+- **Time component** (`19-42-15.123-`) — UTC `HH-MM-SS.mmm`. Lexical sort
+  = chronological order.
+- **8 hex chars random tail** — collision-resistant for two flushes at
+  the same millisecond.
+- **`.jsonl`** — one JSON-encoded event per line, trailing newline.
+
+Override via the `keyFor` option for tenant-fan-out or hourly partitions.
+
+## Flush triggers
+
+Whichever fires first:
+
+| Trigger | Default | Option |
+|---|---|---|
+| Buffer reaches event count | 1000 | `maxBatchSize` |
+| Buffer reaches byte count | 5_000_000 (5 MB) | `maxBatchBytes` |
+| Time since last flush | 5_000 ms | `flushIntervalMs` |
+| Manual | (caller) | `await sink.flush()` |
+| Close | (caller) | `await sink.close()` |
+
+Set `flushIntervalMs: 0` to disable the periodic timer (size-only flushing).
+
+## Crash safety
+
+Unflushed events are **lost** on process kill. For stricter durability,
+pair the S3 sink with a synchronous sink (Postgres) for critical events
+— S3 is the long-term archive, not the source of truth between flushes.
+Lower `flushIntervalMs` to shrink the loss window at the cost of more
+S3 PUTs.
+
+## What this sink does NOT do
+
+- **`list` / `prune`** — not implemented. Read audit logs out of S3 via
+  Athena / `s3 ls` / DuckDB; enforce retention via S3 lifecycle policies.
+  The sink is write-only.
+- **Retry on PUT failure** — `onPutError` callback fires once; the batch
+  is dropped. Wire your own retry queue if you need at-least-once.
+- **Multipart upload** — every batch is one PUT. If your batches grow
+  past S3's 5GB PutObject limit you have other problems.
+
+## Integrity across batches
+
+The tamper-evident chain from `withIntegrity()` works across batch
+boundaries automatically. Each event is hashed at append time against
+the prior event's hash; the S3 sink only buffers + flushes — it doesn't
+touch the chain. To verify a chain that spans multiple S3 objects:
+
+```ts
+import { verifyChain } from '@absolutejs/audit';
+
+// Pull every JSONL object back, sort lexically (= chronologically), flatten:
+const allEvents = orderedJsonlBodies.flatMap(body =>
+  body.split('\n').filter(Boolean).map(line => JSON.parse(line))
+);
+const result = await verifyChain(allEvents, secret);
+// { ok: true } or { ok: false, brokenAt: <index> }
+```
+
+## License
+
+[Apache 2.0](../LICENSE). Substrate-adjacent — rides `@absolutejs/audit`
+(BSL Tier A).

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @absolutejs/audit-s3 — S3-compatible `AuditSink` for `@absolutejs/audit`.
+ *
+ * S3 objects are immutable (no real "append"), so the sink buffers events
+ * in memory and flushes them as JSONL files keyed by time. Object keys
+ * are lexically sortable so `aws s3 ls` (or any equivalent) returns
+ * events in chronological order; the date prefix makes lifecycle policies
+ * straightforward ("delete `audit/2026-01-*` after 7 years").
+ *
+ * **Driver-agnostic.** Takes a narrow `put(key, body)` callback so it
+ * works with AWS SDK v3, Cloudflare R2 (via fetch + signed URLs or the
+ * R2 Workers binding), Backblaze B2's S3-compatible API, MinIO, or
+ * anything else that exposes "put a string at a key" semantics. No
+ * `@aws-sdk/client-s3` hard dependency.
+ *
+ * **Flush triggers** (whichever fires first):
+ *   - **Size**: `maxBatchSize` events buffered (default 1000) OR
+ *     `maxBatchBytes` of serialized JSONL (default 5MB).
+ *   - **Time**: `flushIntervalMs` since last flush (default 5_000).
+ *   - **Manual**: `await sink.flush()` from the caller.
+ *   - **Close**: `await sink.close()` drains the buffer + clears the
+ *     interval timer.
+ *
+ * **Tamper-evidence works across batches automatically.** The integrity
+ * chain (`@absolutejs/audit`'s `withIntegrity()`) computes a hash on
+ * every `append()` against the prior event's hash. The S3 sink only
+ * buffers + flushes — it doesn't touch the chain. So events split
+ * across multiple JSONL files still verify end-to-end via `verifyChain`.
+ *
+ * **No `list` / `prune`** by design. Reading audit logs out of S3 is a
+ * separate operation (Athena, `s3 ls`, etc.); enforcing retention is
+ * S3 lifecycle policies. The sink is write-only — pair with a
+ * `memorySink` (hot tail for queries) or `audit-postgres` (queryable
+ * durable companion) when the host needs `list`.
+ *
+ * **Crash safety.** Unflushed events are lost on process kill. For
+ * stricter durability, pair with a synchronous sink (Postgres) for
+ * critical events; the S3 sink is the long-term archive, not the
+ * source of truth between flushes. Lower `flushIntervalMs` to shrink
+ * the loss window at the cost of more S3 PUTs.
+ */
+import type { AuditEvent, AuditSink } from '@absolutejs/audit';
+/**
+ * The single S3 operation the sink needs. Implement against your
+ * preferred SDK; the sink calls `put(key, body, contentType)` with
+ * `'application/x-ndjson'` and expects a resolved Promise on success
+ * or a rejection on failure.
+ */
+export type S3PutFn = (key: string, body: string, contentType: string) => Promise<void>;
+export type S3KeyOptions = {
+    /** First event's `at` in the batch. */
+    batchStart: number;
+    /** Last event's `at` in the batch. */
+    batchEnd: number;
+    /** How many events the batch contains. */
+    eventCount: number;
+};
+export type CreateS3AuditSinkOptions = {
+    /**
+     * The S3 PUT operation. Receives the object key (relative to whatever
+     * bucket your put implementation targets), the serialized JSONL body,
+     * and a content-type hint (`'application/x-ndjson'`).
+     */
+    put: S3PutFn;
+    /**
+     * Key prefix. Default `'audit/'`. Useful when one bucket holds
+     * multiple audit streams — `'audit/tenant-A/'`, `'audit/system/'`, etc.
+     */
+    prefix?: string;
+    /**
+     * Build the object key from batch metadata. Default produces keys
+     * like `audit/2026-05-30/19-42-15.123-abcd1234.jsonl`. The default
+     * is intentionally sortable end-to-end so `s3 ls --prefix audit/`
+     * returns chronological order; override only when you need a
+     * different layout (e.g., per-tenant fan-out, hourly partitions).
+     */
+    keyFor?: (params: S3KeyOptions) => string;
+    /** Flush when the buffer reaches this many events. Default 1000. */
+    maxBatchSize?: number;
+    /** Flush when serialized JSONL would exceed this many bytes. Default 5MB. */
+    maxBatchBytes?: number;
+    /**
+     * Flush every N ms regardless of buffer state. Set to `0` or
+     * `Infinity` to disable the timer (size/manual-only flushing).
+     * Default 5000.
+     */
+    flushIntervalMs?: number;
+    /**
+     * Called when a PUT fails. Default `console.error`. The batch is
+     * NOT retried automatically — wire your own retry queue via this
+     * hook if you need at-least-once.
+     */
+    onPutError?: (error: unknown, key: string, events: AuditEvent[]) => void;
+    /** Override `Date.now` for tests. */
+    clock?: () => number;
+};
+/**
+ * Default object-key generator. Produces lexically-sortable keys of
+ * the form `<prefix><YYYY-MM-DD>/<HH-MM-SS>.<ms>-<rand>.jsonl`. The
+ * date prefix is the natural lifecycle-policy boundary; the time
+ * suffix is unique within the millisecond via a random tail so two
+ * flushes at the same instant don't collide.
+ */
+export declare const defaultKeyFor: (prefix: string) => (params: S3KeyOptions) => string;
+declare const DEFAULTS: {
+    flushIntervalMs: number;
+    maxBatchBytes: number;
+    maxBatchSize: number;
+    prefix: string;
+};
+export declare const createS3AuditSink: (options: CreateS3AuditSinkOptions) => AuditSink;
+export { DEFAULTS as S3_AUDIT_SINK_DEFAULTS };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,CACrB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,KACf,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,MAAM,YAAY,GAAG;IAC1B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACtC;;;;OAIG;IACH,GAAG,EAAE,OAAO,CAAC;IACb;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,MAAM,CAAC;IAC1C,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,IAAI,CAAC;IACzE,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACrB,CAAC;AAQF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,MAAM,MACd,QAAQ,YAAY,KAAG,MAUvB,CAAC;AAEH,QAAA,MAAM,QAAQ;;;;;CAKb,CAAC;AAIF,eAAO,MAAM,iBAAiB,GAC7B,SAAS,wBAAwB,KAC/B,SA6GF,CAAC;AAKF,OAAO,EAAE,QAAQ,IAAI,sBAAsB,EAAE,CAAC"}

package/dist/index.js

@@ -0,0 +1,106 @@
+// @bun
+// src/index.ts
+var TWO = 2;
+var pad = (n, width) => String(n).padStart(width, "0");
+var defaultKeyFor = (prefix) => (params) => {
+  const date = new Date(params.batchStart);
+  const datePart = `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1, TWO)}-${pad(date.getUTCDate(), TWO)}`;
+  const timePart = `${pad(date.getUTCHours(), TWO)}-${pad(date.getUTCMinutes(), TWO)}-${pad(date.getUTCSeconds(), TWO)}.${pad(date.getUTCMilliseconds(), 3)}`;
+  const rand = Math.floor(Math.random() * 4294967295).toString(16).padStart(8, "0");
+  return `${prefix}${datePart}/${timePart}-${rand}.jsonl`;
+};
+var DEFAULTS = {
+  flushIntervalMs: 5000,
+  maxBatchBytes: 5000000,
+  maxBatchSize: 1000,
+  prefix: "audit/"
+};
+var CONTENT_TYPE = "application/x-ndjson";
+var createS3AuditSink = (options) => {
+  const prefix = options.prefix ?? DEFAULTS.prefix;
+  const maxBatchSize = options.maxBatchSize ?? DEFAULTS.maxBatchSize;
+  const maxBatchBytes = options.maxBatchBytes ?? DEFAULTS.maxBatchBytes;
+  const flushIntervalMs = options.flushIntervalMs ?? DEFAULTS.flushIntervalMs;
+  const keyFor = options.keyFor ?? defaultKeyFor(prefix);
+  const clock = options.clock ?? Date.now;
+  const onPutError = options.onPutError ?? ((error, key) => console.error(`[audit-s3] PUT failed for "${key}":`, error));
+  const { put } = options;
+  let buffer = [];
+  let bufferedBytes = 0;
+  let closed = false;
+  let flushChain = Promise.resolve();
+  let timer;
+  const doFlush = async () => {
+    if (buffer.length === 0)
+      return;
+    const snapshot = buffer;
+    buffer = [];
+    bufferedBytes = 0;
+    const events = snapshot.map((b) => b.event);
+    const body = snapshot.map((b) => b.line).join(`
+`) + `
+`;
+    const batchStart = events[0].at;
+    const batchEnd = events[events.length - 1].at;
+    const key = keyFor({
+      batchEnd,
+      batchStart,
+      eventCount: events.length
+    });
+    try {
+      await put(key, body, CONTENT_TYPE);
+    } catch (error) {
+      onPutError(error, key, events);
+    }
+  };
+  const flush = () => {
+    const next = flushChain.then(() => doFlush());
+    flushChain = next.catch(() => {});
+    return next;
+  };
+  if (flushIntervalMs > 0 && Number.isFinite(flushIntervalMs) && typeof setInterval !== "undefined") {
+    timer = setInterval(() => {
+      flush();
+    }, flushIntervalMs);
+    if (timer && typeof timer.unref === "function") {
+      timer.unref();
+    }
+  }
+  return {
+    append: (event) => {
+      if (closed) {
+        throw new Error("[audit-s3] sink is closed");
+      }
+      const line = JSON.stringify(event);
+      const bytes = line.length + 1;
+      buffer.push({ bytes, event, line });
+      bufferedBytes += bytes;
+      if (buffer.length >= maxBatchSize || bufferedBytes >= maxBatchBytes) {
+        flush();
+      }
+    },
+    close: async () => {
+      if (closed)
+        return;
+      closed = true;
+      if (timer !== undefined) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+      await flush();
+      await flushChain;
+    },
+    flush: async () => {
+      await flush();
+    },
+    name: "s3"
+  };
+};
+export {
+  defaultKeyFor,
+  createS3AuditSink,
+  DEFAULTS as S3_AUDIT_SINK_DEFAULTS
+};
+
+//# debugId=6DDB6A7CA64CA89F64756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * @absolutejs/audit-s3 — S3-compatible `AuditSink` for `@absolutejs/audit`.\n *\n * S3 objects are immutable (no real \"append\"), so the sink buffers events\n * in memory and flushes them as JSONL files keyed by time. Object keys\n * are lexically sortable so `aws s3 ls` (or any equivalent) returns\n * events in chronological order; the date prefix makes lifecycle policies\n * straightforward (\"delete `audit/2026-01-*` after 7 years\").\n *\n * **Driver-agnostic.** Takes a narrow `put(key, body)` callback so it\n * works with AWS SDK v3, Cloudflare R2 (via fetch + signed URLs or the\n * R2 Workers binding), Backblaze B2's S3-compatible API, MinIO, or\n * anything else that exposes \"put a string at a key\" semantics. No\n * `@aws-sdk/client-s3` hard dependency.\n *\n * **Flush triggers** (whichever fires first):\n *   - **Size**: `maxBatchSize` events buffered (default 1000) OR\n *     `maxBatchBytes` of serialized JSONL (default 5MB).\n *   - **Time**: `flushIntervalMs` since last flush (default 5_000).\n *   - **Manual**: `await sink.flush()` from the caller.\n *   - **Close**: `await sink.close()` drains the buffer + clears the\n *     interval timer.\n *\n * **Tamper-evidence works across batches automatically.** The integrity\n * chain (`@absolutejs/audit`'s `withIntegrity()`) computes a hash on\n * every `append()` against the prior event's hash. The S3 sink only\n * buffers + flushes — it doesn't touch the chain. So events split\n * across multiple JSONL files still verify end-to-end via `verifyChain`.\n *\n * **No `list` / `prune`** by design. Reading audit logs out of S3 is a\n * separate operation (Athena, `s3 ls`, etc.); enforcing retention is\n * S3 lifecycle policies. The sink is write-only — pair with a\n * `memorySink` (hot tail for queries) or `audit-postgres` (queryable\n * durable companion) when the host needs `list`.\n *\n * **Crash safety.** Unflushed events are lost on process kill. For\n * stricter durability, pair with a synchronous sink (Postgres) for\n * critical events; the S3 sink is the long-term archive, not the\n * source of truth between flushes. Lower `flushIntervalMs` to shrink\n * the loss window at the cost of more S3 PUTs.\n */\nimport type { AuditEvent, AuditSink } from '@absolutejs/audit';\n\n/**\n * The single S3 operation the sink needs. Implement against your\n * preferred SDK; the sink calls `put(key, body, contentType)` with\n * `'application/x-ndjson'` and expects a resolved Promise on success\n * or a rejection on failure.\n */\nexport type S3PutFn = (\n\tkey: string,\n\tbody: string,\n\tcontentType: string\n) => Promise<void>;\n\nexport type S3KeyOptions = {\n\t/** First event's `at` in the batch. */\n\tbatchStart: number;\n\t/** Last event's `at` in the batch. */\n\tbatchEnd: number;\n\t/** How many events the batch contains. */\n\teventCount: number;\n};\n\nexport type CreateS3AuditSinkOptions = {\n\t/**\n\t * The S3 PUT operation. Receives the object key (relative to whatever\n\t * bucket your put implementation targets), the serialized JSONL body,\n\t * and a content-type hint (`'application/x-ndjson'`).\n\t */\n\tput: S3PutFn;\n\t/**\n\t * Key prefix. Default `'audit/'`. Useful when one bucket holds\n\t * multiple audit streams — `'audit/tenant-A/'`, `'audit/system/'`, etc.\n\t */\n\tprefix?: string;\n\t/**\n\t * Build the object key from batch metadata. Default produces keys\n\t * like `audit/2026-05-30/19-42-15.123-abcd1234.jsonl`. The default\n\t * is intentionally sortable end-to-end so `s3 ls --prefix audit/`\n\t * returns chronological order; override only when you need a\n\t * different layout (e.g., per-tenant fan-out, hourly partitions).\n\t */\n\tkeyFor?: (params: S3KeyOptions) => string;\n\t/** Flush when the buffer reaches this many events. Default 1000. */\n\tmaxBatchSize?: number;\n\t/** Flush when serialized JSONL would exceed this many bytes. Default 5MB. */\n\tmaxBatchBytes?: number;\n\t/**\n\t * Flush every N ms regardless of buffer state. Set to `0` or\n\t * `Infinity` to disable the timer (size/manual-only flushing).\n\t * Default 5000.\n\t */\n\tflushIntervalMs?: number;\n\t/**\n\t * Called when a PUT fails. Default `console.error`. The batch is\n\t * NOT retried automatically — wire your own retry queue via this\n\t * hook if you need at-least-once.\n\t */\n\tonPutError?: (error: unknown, key: string, events: AuditEvent[]) => void;\n\t/** Override `Date.now` for tests. */\n\tclock?: () => number;\n};\n\nconst TWO = 2;\nconst FOUR = 4;\nconst TEN = 10;\n\nconst pad = (n: number, width: number): string => String(n).padStart(width, '0');\n\n/**\n * Default object-key generator. Produces lexically-sortable keys of\n * the form `<prefix><YYYY-MM-DD>/<HH-MM-SS>.<ms>-<rand>.jsonl`. The\n * date prefix is the natural lifecycle-policy boundary; the time\n * suffix is unique within the millisecond via a random tail so two\n * flushes at the same instant don't collide.\n */\nexport const defaultKeyFor =\n\t(prefix: string) =>\n\t(params: S3KeyOptions): string => {\n\t\tconst date = new Date(params.batchStart);\n\t\tconst datePart = `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1, TWO)}-${pad(date.getUTCDate(), TWO)}`;\n\t\tconst timePart = `${pad(date.getUTCHours(), TWO)}-${pad(date.getUTCMinutes(), TWO)}-${pad(date.getUTCSeconds(), TWO)}.${pad(date.getUTCMilliseconds(), 3)}`;\n\t\t// 8 hex chars of randomness — collision probability is\n\t\t// negligible for two flushes at the same millisecond.\n\t\tconst rand = Math.floor(Math.random() * 0xffffffff)\n\t\t\t.toString(16)\n\t\t\t.padStart(8, '0');\n\t\treturn `${prefix}${datePart}/${timePart}-${rand}.jsonl`;\n\t};\n\nconst DEFAULTS = {\n\tflushIntervalMs: 5000,\n\tmaxBatchBytes: 5_000_000,\n\tmaxBatchSize: 1000,\n\tprefix: 'audit/'\n};\n\nconst CONTENT_TYPE = 'application/x-ndjson';\n\nexport const createS3AuditSink = (\n\toptions: CreateS3AuditSinkOptions\n): AuditSink => {\n\tconst prefix = options.prefix ?? DEFAULTS.prefix;\n\tconst maxBatchSize = options.maxBatchSize ?? DEFAULTS.maxBatchSize;\n\tconst maxBatchBytes = options.maxBatchBytes ?? DEFAULTS.maxBatchBytes;\n\tconst flushIntervalMs =\n\t\toptions.flushIntervalMs ?? DEFAULTS.flushIntervalMs;\n\tconst keyFor = options.keyFor ?? defaultKeyFor(prefix);\n\tconst clock = options.clock ?? Date.now;\n\tconst onPutError =\n\t\toptions.onPutError ??\n\t\t((error, key) =>\n\t\t\tconsole.error(`[audit-s3] PUT failed for \"${key}\":`, error));\n\tconst { put } = options;\n\n\ttype Buffered = { event: AuditEvent; line: string; bytes: number };\n\tlet buffer: Buffered[] = [];\n\tlet bufferedBytes = 0;\n\tlet closed = false;\n\t// A single in-flight flush chain so concurrent flush() calls don't\n\t// race on `buffer`. Each flush takes a SNAPSHOT of the buffer and\n\t// clears it synchronously before the PUT awaits.\n\tlet flushChain: Promise<void> = Promise.resolve();\n\tlet timer: ReturnType<typeof setInterval> | undefined;\n\n\tconst doFlush = async (): Promise<void> => {\n\t\tif (buffer.length === 0) return;\n\t\t// Snapshot + clear synchronously. New appends during the PUT\n\t\t// land in a fresh buffer that flushes on the next trigger.\n\t\tconst snapshot = buffer;\n\t\tbuffer = [];\n\t\tbufferedBytes = 0;\n\t\tconst events = snapshot.map((b) => b.event);\n\t\tconst body = snapshot.map((b) => b.line).join('\\n') + '\\n';\n\t\tconst batchStart = events[0]!.at;\n\t\tconst batchEnd = events[events.length - 1]!.at;\n\t\tconst key = keyFor({\n\t\t\tbatchEnd,\n\t\t\tbatchStart,\n\t\t\teventCount: events.length\n\t\t});\n\t\ttry {\n\t\t\tawait put(key, body, CONTENT_TYPE);\n\t\t} catch (error) {\n\t\t\tonPutError(error, key, events);\n\t\t}\n\t};\n\n\t// Chain flushes so a concurrent flush waits for the prior one. A\n\t// throw doesn't poison the chain — `doFlush` already catches via\n\t// `onPutError`.\n\tconst flush = (): Promise<void> => {\n\t\tconst next = flushChain.then(() => doFlush());\n\t\tflushChain = next.catch(() => {});\n\t\treturn next;\n\t};\n\n\t// Initialize the periodic timer if enabled. `unref()` lets the\n\t// process exit even if the timer is pending — flushes during\n\t// shutdown go through `close()` which awaits the final flush.\n\tif (\n\t\tflushIntervalMs > 0 &&\n\t\tNumber.isFinite(flushIntervalMs) &&\n\t\ttypeof setInterval !== 'undefined'\n\t) {\n\t\ttimer = setInterval(() => {\n\t\t\tvoid flush();\n\t\t}, flushIntervalMs);\n\t\t// In Node/Bun, `unref()` exists on the returned Timer object.\n\t\tif (timer && typeof (timer as { unref?: () => void }).unref === 'function') {\n\t\t\t(timer as { unref: () => void }).unref();\n\t\t}\n\t}\n\n\treturn {\n\t\tappend: (event) => {\n\t\t\tif (closed) {\n\t\t\t\tthrow new Error('[audit-s3] sink is closed');\n\t\t\t}\n\t\t\tconst line = JSON.stringify(event);\n\t\t\tconst bytes = line.length + 1; // +1 for the newline\n\t\t\tbuffer.push({ bytes, event, line });\n\t\t\tbufferedBytes += bytes;\n\t\t\t// Synchronous size-based trigger. Fire-and-forget the flush;\n\t\t\t// `flush()` is chained so the next size trigger queues behind\n\t\t\t// the in-flight PUT instead of racing.\n\t\t\tif (\n\t\t\t\tbuffer.length >= maxBatchSize ||\n\t\t\t\tbufferedBytes >= maxBatchBytes\n\t\t\t) {\n\t\t\t\tvoid flush();\n\t\t\t}\n\t\t},\n\t\tclose: async () => {\n\t\t\tif (closed) return;\n\t\t\tclosed = true;\n\t\t\tif (timer !== undefined) {\n\t\t\t\tclearInterval(timer);\n\t\t\t\ttimer = undefined;\n\t\t\t}\n\t\t\t// Final flush — wait for any pending flush PLUS one more so\n\t\t\t// the buffer drains.\n\t\t\tawait flush();\n\t\t\tawait flushChain;\n\t\t},\n\t\tflush: async () => {\n\t\t\tawait flush();\n\t\t},\n\t\tname: 's3'\n\t};\n};\n\n// `clock` is currently only available through the option, not exposed\n// in the returned API. Reserve the export in case a tested-driven user\n// needs it via the default keyFor.\nexport { DEFAULTS as S3_AUDIT_SINK_DEFAULTS };\n"
+  ],
+  "mappings": "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",
+  "debugId": "6DDB6A7CA64CA89F64756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "@absolutejs/audit-s3",
+	"version": "0.0.1",
+	"description": "S3-compatible AuditSink for @absolutejs/audit. Buffered JSONL writes to AWS S3 / Cloudflare R2 / Backblaze B2 / MinIO. Time-sortable object keys; WORM-bucket-friendly for compliance retention.",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/absolutejs/audit-adapters.git",
+		"directory": "s3"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"license": "Apache-2.0",
+	"author": "Alex Kahn",
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"audit",
+		"s3",
+		"r2",
+		"cloudflare",
+		"minio",
+		"backblaze",
+		"absolutejs",
+		"audit-log",
+		"compliance",
+		"worm"
+	],
+	"scripts": {
+		"build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=bun --external @absolutejs/audit && tsc --project tsconfig.build.json",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"format": "prettier --write \"./**/*.{ts,json,md}\"",
+		"release": "bun run format && bun run build && bun publish"
+	},
+	"peerDependencies": {
+		"@absolutejs/audit": ">= 0.0.1"
+	},
+	"devDependencies": {
+		"@absolutejs/audit": "^0.0.1",
+		"@types/bun": "1.3.14",
+		"prettier": "3.5.3",
+		"typescript": "5.8.3"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	]
+}