@lenso/audit 0.0.0-stage → 0.2.0

package/dist/index-ph1dkars.js

@@ -0,0 +1,169 @@
+import {
+  invalid,
+  object,
+  uuid,
+  time,
+  scope,
+  actor,
+  summaryPolicy,
+  eventInput,
+  query
+} from "./index-xk4zknet.js";
+import {
+  AuditError2,
+  AuditOutcomeUnknownError2,
+  sameScope2
+} from "./index-dxwdr6tz.js";
+
+// src/service.ts
+function createAuditService2(options) {
+  const { repository, authority, report } = options;
+  const policy = summaryPolicy(options.summaryPolicy ?? {});
+  const maxPageSize = options.maxPageSize ?? 100;
+  if (!Number.isSafeInteger(maxPageSize) || maxPageSize < 1 || maxPageSize > 500)
+    invalid();
+  const clock = options.clock ?? Date.now;
+  const receipts = new WeakMap;
+  async function identity(principal, scope, operation) {
+    try {
+      return actor(await authority.resolve(principal, scope, operation));
+    } catch {
+      throw new AuditError2("unauthorized");
+    }
+  }
+  async function diagnostic(mode, stage) {
+    try {
+      await report?.(Object.freeze({ mode, stage, code: "storage-failed" }));
+    } catch {
+      throw new AuditError2("diagnostics-failed");
+    }
+  }
+  async function storage(work) {
+    try {
+      return await work();
+    } catch {
+      throw new AuditError2("storage-failed");
+    }
+  }
+  async function persist(event) {
+    if (event.relation) {
+      if (event.relation.eventId === event.id)
+        invalid();
+      const previous = await storage(() => repository.get(event.scope, event.relation.eventId));
+      if (!previous)
+        throw new AuditError2("relation-missing");
+      if (!sameScope2(previous.scope, event.scope))
+        throw new AuditError2("storage-failed");
+      if (event.relation.kind === "outcome" && (previous.result !== "intent" || event.result === "intent" || previous.action !== event.action || previous.target.type !== event.target.type || previous.target.id !== event.target.id))
+        invalid();
+    }
+    const status = await storage(() => repository.insert(event));
+    if (status === "conflict")
+      throw new AuditError2("duplicate-conflict");
+    if (status !== "inserted" && status !== "duplicate")
+      throw new AuditError2("storage-failed");
+    const stored = status === "duplicate" ? await storage(() => repository.get(event.scope, event.id)) : event;
+    if (!stored)
+      throw new AuditError2("storage-failed");
+    return { status, event: stored };
+  }
+  async function make(input, principal) {
+    const data = eventInput(input, policy);
+    const actor = await identity(principal, data.scope, "append");
+    return Object.freeze({ ...data, actor, recordedAt: time(clock()) });
+  }
+  return {
+    async append(input, principal) {
+      return persist(await make(input, principal));
+    },
+    async appendBestEffort(input, principal) {
+      if (!report)
+        throw new AuditError2("diagnostics-required");
+      const event = await make(input, principal);
+      try {
+        return await persist(event);
+      } catch (error) {
+        if (!(error instanceof AuditError2) || error.code !== "storage-failed")
+          throw error;
+        await diagnostic("best-effort", "append");
+        return { status: "unconfirmed", code: "storage-failed" };
+      }
+    },
+    async get(input, principal) {
+      const raw = object(input, ["scope", "id"]);
+      const scope2 = scope(raw.scope);
+      const id = uuid(raw.id);
+      await identity(principal, scope2, "query");
+      const event = await storage(() => repository.get(scope2, id));
+      if (event && !sameScope2(event.scope, scope2))
+        throw new AuditError2("storage-failed");
+      return event;
+    },
+    async query(input, principal) {
+      const query2 = query(input, maxPageSize);
+      await identity(principal, query2.scope, "query");
+      const rows = await storage(() => repository.list({ ...query2, limit: query2.limit + 1 }));
+      if (rows.some((event) => !sameScope2(event.scope, query2.scope)))
+        throw new AuditError2("storage-failed");
+      const events = rows.slice(0, query2.limit);
+      const last = events.at(-1);
+      return {
+        events,
+        nextCursor: rows.length > query2.limit && last ? { recordedAt: last.recordedAt, id: last.id } : null
+      };
+    },
+    async prepare(input, principal) {
+      if (repository.durableIntents !== true)
+        throw new AuditError2("strict-unavailable");
+      const event = await make(input, principal);
+      if (event.result !== "intent" || event.relation)
+        invalid();
+      let result;
+      try {
+        result = await persist(event);
+      } catch (error) {
+        if (error instanceof AuditError2 && error.code === "storage-failed")
+          await diagnostic("strict", "intent");
+        throw error;
+      }
+      if (result.status === "duplicate")
+        return { status: "already-recorded", intentId: event.id };
+      const receipt = Object.freeze({ intentId: event.id });
+      receipts.set(receipt, event);
+      return { status: "ready", receipt };
+    },
+    async complete(receipt, outcome) {
+      const intent = receipts.get(receipt);
+      if (!intent)
+        throw new AuditError2("invalid-receipt");
+      try {
+        object(outcome, ["id", "occurredAt", "result", "reasonCode", "summary"]);
+        if (!["success", "failure", "denied", "unknown"].includes(outcome.result))
+          invalid();
+        const data = eventInput({
+          ...outcome,
+          scope: intent.scope,
+          action: intent.action,
+          target: intent.target,
+          ...intent.correlationId ? { correlationId: intent.correlationId } : {},
+          relation: { kind: "outcome", eventId: intent.id }
+        }, policy);
+        const event = Object.freeze({
+          ...data,
+          actor: intent.actor,
+          recordedAt: time(clock())
+        });
+        return (await persist(event)).event;
+      } catch {
+        try {
+          await diagnostic("strict", "outcome");
+        } catch {
+          throw new AuditOutcomeUnknownError2(intent.id, true);
+        }
+        throw new AuditOutcomeUnknownError2(intent.id);
+      }
+    }
+  };
+}
+
+export { createAuditService2 };

package/dist/index-xk4zknet.js

@@ -0,0 +1,191 @@
+import {
+  AuditError2
+} from "./index-dxwdr6tz.js";
+
+// src/validation.ts
+var forbidden = /secret|password|token|credential|cookie|authorization|digest|hash|body|payload|email|phone|address|__proto__|constructor|prototype/i;
+var results = ["intent", "success", "failure", "denied", "unknown"];
+var eventIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+function invalid() {
+  throw new AuditError2("invalid-input");
+}
+function object(value, keys) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    invalid();
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null)
+    invalid();
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string" || keys && !keys.includes(key))
+      invalid();
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!("value" in descriptor) || !descriptor.enumerable)
+      invalid();
+  }
+  return value;
+}
+function identifier(value, max = 128) {
+  if (typeof value !== "string" || value.length > max || !/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/.test(value) || value.includes("://"))
+    invalid();
+  return value;
+}
+function uuid(value) {
+  if (typeof value !== "string" || !eventIdPattern.test(value))
+    invalid();
+  return value;
+}
+function time(value) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > 8640000000000000)
+    invalid();
+  return value;
+}
+function scope(value) {
+  const input = object(value, ["tenantId", "scopeId"]);
+  return Object.freeze({
+    tenantId: input.tenantId === null ? null : identifier(input.tenantId),
+    scopeId: identifier(input.scopeId)
+  });
+}
+function actor(value) {
+  const input = object(value);
+  if (input.kind === "system") {
+    object(input, ["kind", "systemId"]);
+    return Object.freeze({ kind: "system", systemId: identifier(input.systemId) });
+  }
+  object(input, ["kind", "realmId", "subjectId"]);
+  if (!["user", "guest", "service"].includes(input.kind))
+    invalid();
+  if (typeof input.realmId !== "string" || !input.realmId.trim() || input.realmId.length > 256 || /\s/.test(input.realmId) || typeof input.subjectId !== "string" || !input.subjectId.trim() || input.subjectId.length > 512)
+    invalid();
+  return Object.freeze({
+    kind: input.kind,
+    realmId: input.realmId,
+    subjectId: input.subjectId
+  });
+}
+function summaryPolicy(data) {
+  const policy = object(data);
+  const copied = {};
+  if (Object.keys(policy).length > 100)
+    invalid();
+  for (const [action, fields] of Object.entries(policy)) {
+    identifier(action);
+    const rules = object(fields);
+    if (Object.keys(rules).length > 16)
+      invalid();
+    const target = {};
+    for (const [key, value] of Object.entries(rules)) {
+      identifier(key, 64);
+      if (forbidden.test(key))
+        invalid();
+      const rule = object(value);
+      if (rule.type === "boolean") {
+        object(rule, ["type"]);
+        target[key] = Object.freeze({ type: "boolean" });
+      } else if (rule.type === "integer") {
+        object(rule, ["type", "min", "max"]);
+        if (!Number.isSafeInteger(rule.min) || !Number.isSafeInteger(rule.max) || rule.min > rule.max)
+          invalid();
+        target[key] = Object.freeze({
+          type: "integer",
+          min: rule.min,
+          max: rule.max
+        });
+      } else if (rule.type === "enum") {
+        object(rule, ["type", "values"]);
+        if (!Array.isArray(rule.values) || !rule.values.length || rule.values.length > 32)
+          invalid();
+        target[key] = Object.freeze({
+          type: "enum",
+          values: Object.freeze(rule.values.map((literal) => identifier(literal, 64)))
+        });
+      } else
+        invalid();
+    }
+    copied[action] = Object.freeze(target);
+  }
+  return Object.freeze(copied);
+}
+function eventInput(data, policy) {
+  const raw = object(data, [
+    "id",
+    "occurredAt",
+    "scope",
+    "action",
+    "target",
+    "result",
+    "reasonCode",
+    "correlationId",
+    "summary",
+    "relation"
+  ]);
+  const action = identifier(raw.action);
+  const target = object(raw.target, ["type", "id"]);
+  if (!results.includes(raw.result))
+    invalid();
+  const summary = {};
+  for (const [key, value] of Object.entries(raw.summary === undefined ? {} : object(raw.summary))) {
+    const rule = Object.hasOwn(policy, action) && Object.hasOwn(policy[action], key) ? policy[action][key] : undefined;
+    if (!rule || forbidden.test(key))
+      invalid();
+    if (rule.type === "boolean" && typeof value !== "boolean" || rule.type === "integer" && (typeof value !== "number" || !Number.isSafeInteger(value) || value < rule.min || value > rule.max) || rule.type === "enum" && (typeof value !== "string" || !rule.values.includes(value)))
+      invalid();
+    summary[key] = value;
+  }
+  const relation = raw.relation === undefined ? undefined : object(raw.relation, ["kind", "eventId"]);
+  if (relation && !["correction", "outcome"].includes(relation.kind))
+    invalid();
+  return Object.freeze({
+    id: uuid(raw.id),
+    occurredAt: time(raw.occurredAt),
+    scope: scope(raw.scope),
+    action,
+    target: Object.freeze({ type: identifier(target.type, 64), id: identifier(target.id, 256) }),
+    result: raw.result,
+    reasonCode: identifier(raw.reasonCode, 64),
+    ...raw.correlationId === undefined ? {} : { correlationId: identifier(raw.correlationId) },
+    summary: Object.freeze(summary),
+    ...relation ? {
+      relation: Object.freeze({
+        kind: relation.kind,
+        eventId: uuid(relation.eventId)
+      })
+    } : {}
+  });
+}
+function query(value, maxPageSize) {
+  const raw = object(value, [
+    "scope",
+    "limit",
+    "cursor",
+    "action",
+    "target",
+    "result",
+    "correlationId",
+    "recordedFrom",
+    "recordedTo"
+  ]);
+  const limit = raw.limit ?? Math.min(50, maxPageSize);
+  if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1 || limit > maxPageSize)
+    invalid();
+  const target = raw.target === undefined ? undefined : object(raw.target, ["type", "id"]);
+  const cursor = raw.cursor === undefined ? undefined : object(raw.cursor, ["recordedAt", "id"]);
+  if (raw.result !== undefined && !results.includes(raw.result))
+    invalid();
+  const result = {
+    scope: scope(raw.scope),
+    limit,
+    ...cursor ? { cursor: { recordedAt: time(cursor.recordedAt), id: uuid(cursor.id) } } : {},
+    ...raw.action === undefined ? {} : { action: identifier(raw.action) },
+    ...target ? { target: { type: identifier(target.type, 64), id: identifier(target.id, 256) } } : {},
+    ...raw.result === undefined ? {} : { result: raw.result },
+    ...raw.correlationId === undefined ? {} : { correlationId: identifier(raw.correlationId) },
+    ...raw.recordedFrom === undefined ? {} : { recordedFrom: time(raw.recordedFrom) },
+    ...raw.recordedTo === undefined ? {} : { recordedTo: time(raw.recordedTo) }
+  };
+  if (result.recordedFrom !== undefined && result.recordedTo !== undefined && result.recordedFrom > result.recordedTo)
+    invalid();
+  return result;
+}
+
+export { eventIdPattern, invalid, object, uuid, time, scope, actor, summaryPolicy, eventInput, query };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./contracts";
+export * from "./service";

package/dist/index.js

@@ -0,0 +1,16 @@
+import {
+  createAuditService2
+} from "./index-ph1dkars.js";
+import {
+  AuditError2,
+  AuditOutcomeUnknownError2,
+  sameScope2,
+  sameEvent2
+} from "./index-dxwdr6tz.js";
+export {
+  AuditError2 as AuditError,
+  AuditOutcomeUnknownError2 as AuditOutcomeUnknownError,
+  createAuditService2 as createAuditService,
+  sameEvent2 as sameEvent,
+  sameScope2 as sameScope
+};

package/dist/manage.d.ts

@@ -0,0 +1,119 @@
+import { type Plugin } from "@lenso/core";
+import { z } from "zod";
+import type { AuditService } from "./service";
+declare const queryInput: z.ZodObject<{
+    scope: z.ZodObject<{
+        tenantId: z.ZodNullable<z.ZodString>;
+        scopeId: z.ZodString;
+    }, z.core.$strict>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodObject<{
+        recordedAt: z.ZodNumber;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+    action: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+    result: z.ZodOptional<z.ZodEnum<{
+        denied: "denied";
+        failure: "failure";
+        intent: "intent";
+        success: "success";
+        unknown: "unknown";
+    }>>;
+    correlationId: z.ZodOptional<z.ZodString>;
+    recordedFrom: z.ZodOptional<z.ZodNumber>;
+    recordedTo: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** Creating this companion does not install it or open a transport. No append tool is declared. */
+export declare function createAuditManage<P>(options: {
+    id: string;
+    audit: Plugin<AuditService<P>>;
+}): {
+    plugin: Plugin<{
+        query(input: z.input<typeof queryInput>, context: {
+            principal: P;
+        }): Promise<import("./contracts").AuditPage>;
+    }>;
+    operation: import("@lenso/engine/operations").Operation<{
+        principal: P;
+    }> & {
+        readonly plugin: Plugin<{
+            query(input: z.input<typeof queryInput>, context: {
+                principal: P;
+            }): Promise<import("./contracts").AuditPage>;
+        }>;
+        readonly method: "query";
+        readonly input: z.ZodObject<{
+            scope: z.ZodObject<{
+                tenantId: z.ZodNullable<z.ZodString>;
+                scopeId: z.ZodString;
+            }, z.core.$strict>;
+            limit: z.ZodOptional<z.ZodNumber>;
+            cursor: z.ZodOptional<z.ZodObject<{
+                recordedAt: z.ZodNumber;
+                id: z.ZodString;
+            }, z.core.$strict>>;
+            action: z.ZodOptional<z.ZodString>;
+            target: z.ZodOptional<z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, z.core.$strict>>;
+            result: z.ZodOptional<z.ZodEnum<{
+                denied: "denied";
+                failure: "failure";
+                intent: "intent";
+                success: "success";
+                unknown: "unknown";
+            }>>;
+            correlationId: z.ZodOptional<z.ZodString>;
+            recordedFrom: z.ZodOptional<z.ZodNumber>;
+            recordedTo: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        readonly context: true;
+    };
+    manage: import("@lenso/manage").Manage<Plugin<{
+        query(input: z.input<typeof queryInput>, context: {
+            principal: P;
+        }): Promise<import("./contracts").AuditPage>;
+    }>, readonly [import("@lenso/engine/operations").Operation<{
+        principal: P;
+    }> & {
+        readonly plugin: Plugin<{
+            query(input: z.input<typeof queryInput>, context: {
+                principal: P;
+            }): Promise<import("./contracts").AuditPage>;
+        }>;
+        readonly method: "query";
+        readonly input: z.ZodObject<{
+            scope: z.ZodObject<{
+                tenantId: z.ZodNullable<z.ZodString>;
+                scopeId: z.ZodString;
+            }, z.core.$strict>;
+            limit: z.ZodOptional<z.ZodNumber>;
+            cursor: z.ZodOptional<z.ZodObject<{
+                recordedAt: z.ZodNumber;
+                id: z.ZodString;
+            }, z.core.$strict>>;
+            action: z.ZodOptional<z.ZodString>;
+            target: z.ZodOptional<z.ZodObject<{
+                type: z.ZodString;
+                id: z.ZodString;
+            }, z.core.$strict>>;
+            result: z.ZodOptional<z.ZodEnum<{
+                denied: "denied";
+                failure: "failure";
+                intent: "intent";
+                success: "success";
+                unknown: "unknown";
+            }>>;
+            correlationId: z.ZodOptional<z.ZodString>;
+            recordedFrom: z.ZodOptional<z.ZodNumber>;
+            recordedTo: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        readonly context: true;
+    }]>;
+};
+export {};

package/dist/manage.js

@@ -0,0 +1,59 @@
+import {
+  eventIdPattern
+} from "./index-xk4zknet.js";
+
+// src/manage.ts
+import { definePlugin } from "@lenso/core";
+import { defineOperation } from "@lenso/engine/operations";
+import { defineManage } from "@lenso/manage";
+import { z } from "zod";
+var identifier = (max = 128) => z.string().min(1).max(max).regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/);
+var scope = z.strictObject({ tenantId: identifier().nullable(), scopeId: identifier() });
+var queryInput = z.strictObject({
+  scope,
+  limit: z.number().int().min(1).max(500).optional(),
+  cursor: z.strictObject({
+    recordedAt: z.number().int().nonnegative(),
+    id: z.string().regex(eventIdPattern)
+  }).optional(),
+  action: identifier().optional(),
+  target: z.strictObject({
+    type: identifier(64),
+    id: identifier(256)
+  }).optional(),
+  result: z.enum(["intent", "success", "failure", "denied", "unknown"]).optional(),
+  correlationId: identifier().optional(),
+  recordedFrom: z.number().int().nonnegative().optional(),
+  recordedTo: z.number().int().nonnegative().optional()
+});
+function createAuditManage(options) {
+  const plugin = definePlugin({
+    id: options.id,
+    requires: [options.audit],
+    setup(lifecycle) {
+      const audit = lifecycle.get(options.audit);
+      return {
+        query(input, context) {
+          return audit.query(input, context.principal);
+        }
+      };
+    }
+  });
+  const operation = defineOperation({
+    plugin,
+    method: "query",
+    context: true,
+    input: queryInput,
+    effect: "read",
+    destructive: false,
+    retry: "safe",
+    cancellation: "none",
+    description: "Query audit events within an explicitly authorized tenant and scope.",
+    outputDescription: "A bounded page of whitelist-only audit events, with no global count."
+  });
+  const manage = defineManage({ plugin, operations: [operation] });
+  return { plugin, operation, manage };
+}
+export {
+  createAuditManage
+};

package/dist/plugin.d.ts

@@ -0,0 +1,20 @@
+import type { Plugin } from "@lenso/core";
+import { type ConfigSource } from "@lenso/core/config";
+import { z } from "zod";
+import type { AuditAuthority, AuditReporter, AuditRepository, SummaryPolicy } from "./contracts";
+import { type AuditService } from "./service";
+declare const configSchema: z.ZodObject<{
+    maxPageSize: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const auditConfig: import("@lenso/core").ConfigContract<z.ZodObject<{
+    maxPageSize: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>>;
+export declare function createAuditPlugin<P>(options: {
+    id: string;
+    repository: Plugin<AuditRepository>;
+    authority: Plugin<AuditAuthority<P>>;
+    diagnostics?: Plugin<AuditReporter>;
+    summaryPolicy?: SummaryPolicy;
+    config?: z.input<typeof configSchema> | readonly ConfigSource[];
+}): Plugin<AuditService<P>>;
+export {};

package/dist/plugin.js

@@ -0,0 +1,37 @@
+import {
+  createAuditService2
+} from "./index-ph1dkars.js";
+
+// src/plugin.ts
+import { bindConfig, definePluginConfig } from "@lenso/core/config";
+import { z } from "zod";
+var configSchema = z.strictObject({
+  maxPageSize: z.number().int().min(1).max(500).default(100)
+});
+var auditConfig = definePluginConfig({
+  description: "Audit query page budget; identity and scope policy are trusted service bindings",
+  schema: configSchema
+});
+function createAuditPlugin(options) {
+  return bindConfig(auditConfig, options.config ?? {}, {
+    id: options.id,
+    requires: [
+      options.repository,
+      options.authority,
+      ...options.diagnostics ? [options.diagnostics] : []
+    ],
+    setup(context, config) {
+      return createAuditService2({
+        repository: context.get(options.repository),
+        authority: context.get(options.authority),
+        ...options.diagnostics ? { report: context.get(options.diagnostics) } : {},
+        summaryPolicy: options.summaryPolicy,
+        maxPageSize: config.maxPageSize
+      });
+    }
+  });
+}
+export {
+  auditConfig,
+  createAuditPlugin
+};