@beignet/core 0.0.1

package/src/ports/redaction.ts

@@ -0,0 +1,199 @@
+export const DEFAULT_REDACTED_VALUE = "[redacted]";
+export const DEFAULT_TRUNCATED_VALUE = "[truncated]";
+export const DEFAULT_CIRCULAR_VALUE = "[circular]";
+
+export const DEFAULT_SENSITIVE_KEYS = [
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "api-key",
+  "apikey",
+  "access-token",
+  "refresh-token",
+  "credentials",
+] as const;
+
+export const DEFAULT_SENSITIVE_KEY_TERMS = [
+  "token",
+  "password",
+  "secret",
+  "credential",
+  "private-key",
+  "privatekey",
+] as const;
+
+export interface RedactionDecisionContext {
+  key: string;
+  path: readonly string[];
+  value: unknown;
+}
+
+export interface RedactionOptions {
+  replacement?: string;
+  truncatedValue?: string;
+  circularValue?: string;
+  maxDepth?: number;
+  sensitiveKeys?: readonly string[];
+  sensitiveKeyTerms?: readonly string[];
+  shouldRedactKey?: (context: RedactionDecisionContext) => boolean;
+}
+
+export type Redactor<T = unknown> = (value: T) => T;
+
+export type RedactableHeaders =
+  | Headers
+  | Iterable<readonly [string, unknown]>
+  | Record<string, unknown>;
+
+function normalizeKey(key: string): string {
+  return key.toLowerCase();
+}
+
+export function isSensitiveKey(
+  key: string,
+  options: RedactionOptions = {},
+  context?: Omit<RedactionDecisionContext, "key">,
+): boolean {
+  const normalized = normalizeKey(key);
+  const exactKeys = new Set(
+    [...DEFAULT_SENSITIVE_KEYS, ...(options.sensitiveKeys ?? [])].map(
+      normalizeKey,
+    ),
+  );
+  if (exactKeys.has(normalized)) return true;
+
+  const terms = [
+    ...DEFAULT_SENSITIVE_KEY_TERMS,
+    ...(options.sensitiveKeyTerms ?? []),
+  ].map(normalizeKey);
+  if (terms.some((term) => normalized.includes(term))) return true;
+
+  return (
+    options.shouldRedactKey?.({
+      key,
+      path: context?.path ?? [],
+      value: context?.value,
+    }) ?? false
+  );
+}
+
+function redactUnknown(
+  value: unknown,
+  options: RedactionOptions,
+  path: readonly string[],
+  seen: WeakSet<object>,
+): unknown {
+  const maxDepth = options.maxDepth ?? 6;
+  if (path.length > maxDepth) {
+    return options.truncatedValue ?? DEFAULT_TRUNCATED_VALUE;
+  }
+
+  if (value === null || value === undefined) return value;
+
+  const valueType = typeof value;
+  if (
+    valueType === "string" ||
+    valueType === "number" ||
+    valueType === "boolean"
+  ) {
+    return value;
+  }
+
+  if (valueType === "bigint") {
+    return value.toString();
+  }
+
+  if (value instanceof Date) {
+    return value;
+  }
+
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      stack: value.stack,
+    };
+  }
+
+  if (valueType !== "object") {
+    return String(value);
+  }
+
+  const objectValue = value as object;
+  if (seen.has(objectValue)) {
+    return options.circularValue ?? DEFAULT_CIRCULAR_VALUE;
+  }
+  seen.add(objectValue);
+
+  if (Array.isArray(value)) {
+    const output = value.map((item, index) =>
+      redactUnknown(item, options, [...path, String(index)], seen),
+    );
+    seen.delete(objectValue);
+    return output;
+  }
+
+  const output: Record<string, unknown> = {};
+  for (const [key, nestedValue] of Object.entries(value)) {
+    output[key] = isSensitiveKey(key, options, {
+      path: [...path, key],
+      value: nestedValue,
+    })
+      ? (options.replacement ?? DEFAULT_REDACTED_VALUE)
+      : redactUnknown(nestedValue, options, [...path, key], seen);
+  }
+
+  seen.delete(objectValue);
+  return output;
+}
+
+export function redactValue<T = unknown>(
+  value: T,
+  options: RedactionOptions = {},
+): T {
+  return redactUnknown(value, options, [], new WeakSet()) as T;
+}
+
+function headerEntries(
+  headers: RedactableHeaders,
+): Iterable<readonly [string, unknown]> {
+  if (typeof Headers !== "undefined" && headers instanceof Headers) {
+    const entries: Array<readonly [string, unknown]> = [];
+    headers.forEach((value, key) => {
+      entries.push([key, value]);
+    });
+    return entries;
+  }
+
+  if (
+    typeof (headers as { [Symbol.iterator]?: unknown })[Symbol.iterator] ===
+    "function"
+  ) {
+    return headers as Iterable<readonly [string, unknown]>;
+  }
+
+  return Object.entries(headers);
+}
+
+export function redactHeaders(
+  headers: RedactableHeaders,
+  options: RedactionOptions = {},
+): Record<string, unknown> {
+  const output: Record<string, unknown> = {};
+  for (const [key, value] of headerEntries(headers)) {
+    output[key] = isSensitiveKey(key, options, {
+      path: [key],
+      value,
+    })
+      ? (options.replacement ?? DEFAULT_REDACTED_VALUE)
+      : redactValue(value, options);
+  }
+  return output;
+}
+
+export function createRedactor<T = unknown>(
+  options: RedactionOptions = {},
+): Redactor<T> {
+  return (value) => redactValue(value, options);
+}

package/src/ports/storage.ts

@@ -0,0 +1,282 @@
+export type StorageVisibility = "private" | "public";
+
+export type StorageMetadata = Record<string, string>;
+
+export type StorageBody =
+  | string
+  | ArrayBuffer
+  | Uint8Array
+  | Blob
+  | ReadableStream<Uint8Array>;
+
+export interface StoragePutOptions {
+  contentType?: string;
+  cacheControl?: string;
+  metadata?: StorageMetadata;
+  visibility?: StorageVisibility;
+}
+
+export interface StorageObject {
+  key: string;
+  size: number;
+  contentType?: string;
+  cacheControl?: string;
+  metadata: StorageMetadata;
+  visibility: StorageVisibility;
+  lastModified: Date;
+}
+
+export interface StorageObjectBody extends StorageObject {
+  /**
+   * Whether this object body has already been consumed. Like Fetch response
+   * bodies, storage bodies are one-shot so providers can stream objects without
+   * buffering them.
+   */
+  readonly bodyUsed: boolean;
+  stream(): ReadableStream<Uint8Array>;
+  bytes(): Promise<Uint8Array>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+  text(): Promise<string>;
+}
+
+export interface StoragePort {
+  put(
+    key: string,
+    body: StorageBody,
+    options?: StoragePutOptions,
+  ): Promise<StorageObject>;
+  get(key: string): Promise<StorageObjectBody | null>;
+  stat(key: string): Promise<StorageObject | null>;
+  delete(key: string): Promise<boolean>;
+  exists(key: string): Promise<boolean>;
+  publicUrl(key: string): Promise<string | null>;
+}
+
+export interface MemoryStorageOptions {
+  /**
+   * Base URL used by `publicUrl(...)` for objects written with
+   * `visibility: "public"`.
+   */
+  publicBaseUrl?: string;
+}
+
+type MemoryStorageEntry = StorageObject & {
+  bytes: Uint8Array;
+};
+
+function copyBytes(bytes: Uint8Array): Uint8Array {
+  return new Uint8Array(bytes);
+}
+
+function bytesToArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const buffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buffer).set(bytes);
+  return buffer;
+}
+
+function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  const copy = copyBytes(bytes);
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(copy);
+      controller.close();
+    },
+  });
+}
+
+async function streamToBytes(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  const reader = stream.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done) break;
+      chunks.push(result.value);
+      size += result.value.byteLength;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return bytes;
+}
+
+async function storageBodyToBytes(body: StorageBody): Promise<Uint8Array> {
+  if (typeof body === "string") {
+    return new TextEncoder().encode(body);
+  }
+
+  if (body instanceof Uint8Array) {
+    return copyBytes(body);
+  }
+
+  if (body instanceof ArrayBuffer) {
+    return new Uint8Array(body.slice(0));
+  }
+
+  if (body instanceof Blob) {
+    return new Uint8Array(await body.arrayBuffer());
+  }
+
+  return streamToBytes(body);
+}
+
+function cloneObject(entry: MemoryStorageEntry): StorageObject {
+  return {
+    key: entry.key,
+    size: entry.size,
+    ...(entry.contentType !== undefined
+      ? { contentType: entry.contentType }
+      : {}),
+    ...(entry.cacheControl !== undefined
+      ? { cacheControl: entry.cacheControl }
+      : {}),
+    metadata: { ...entry.metadata },
+    visibility: entry.visibility,
+    lastModified: new Date(entry.lastModified),
+  };
+}
+
+function createObjectBody(entry: MemoryStorageEntry): StorageObjectBody {
+  const object = cloneObject(entry);
+  let bodyUsed = false;
+
+  function consumeBytes(): Uint8Array {
+    if (bodyUsed) {
+      throw new Error("Storage object body has already been consumed.");
+    }
+
+    bodyUsed = true;
+    return copyBytes(entry.bytes);
+  }
+
+  return {
+    ...object,
+    get bodyUsed() {
+      return bodyUsed;
+    },
+    stream() {
+      return bytesToStream(consumeBytes());
+    },
+    async bytes() {
+      return consumeBytes();
+    },
+    async arrayBuffer() {
+      return bytesToArrayBuffer(consumeBytes());
+    },
+    async text() {
+      return new TextDecoder().decode(consumeBytes());
+    },
+  };
+}
+
+function validateStorageKey(key: string): void {
+  if (key.length === 0) {
+    throw new Error("Storage key must not be empty.");
+  }
+
+  if (key.startsWith("/")) {
+    throw new Error("Storage key must not start with '/'.");
+  }
+
+  if (key.endsWith("/")) {
+    throw new Error("Storage key must not end with '/'.");
+  }
+
+  if (key.includes("\\")) {
+    throw new Error("Storage key must use '/' separators, not '\\'.");
+  }
+
+  const segments = key.split("/");
+
+  if (segments.some((segment) => segment === "")) {
+    throw new Error("Storage key must not include empty path segments.");
+  }
+
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    throw new Error("Storage key must not include '.' or '..' segments.");
+  }
+}
+
+function joinPublicUrl(baseUrl: string, key: string): string {
+  const base = baseUrl.replace(/\/+$/, "");
+  const encodedKey = key
+    .split("/")
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+
+  return `${base}/${encodedKey}`;
+}
+
+export function createMemoryStorage(
+  options: MemoryStorageOptions = {},
+): StoragePort {
+  const objects = new Map<string, MemoryStorageEntry>();
+
+  return {
+    async put(key, body, putOptions) {
+      validateStorageKey(key);
+      const bytes = await storageBodyToBytes(body);
+      const entry: MemoryStorageEntry = {
+        key,
+        size: bytes.byteLength,
+        ...(putOptions?.contentType !== undefined
+          ? { contentType: putOptions.contentType }
+          : {}),
+        ...(putOptions?.cacheControl !== undefined
+          ? { cacheControl: putOptions.cacheControl }
+          : {}),
+        metadata: { ...(putOptions?.metadata ?? {}) },
+        visibility: putOptions?.visibility ?? "private",
+        lastModified: new Date(),
+        bytes,
+      };
+
+      objects.set(key, entry);
+
+      return cloneObject(entry);
+    },
+    async get(key) {
+      validateStorageKey(key);
+      const entry = objects.get(key);
+      if (!entry) return null;
+
+      return createObjectBody(entry);
+    },
+    async stat(key) {
+      validateStorageKey(key);
+      const entry = objects.get(key);
+      if (!entry) return null;
+
+      return cloneObject(entry);
+    },
+    async delete(key) {
+      validateStorageKey(key);
+      return objects.delete(key);
+    },
+    async exists(key) {
+      validateStorageKey(key);
+      return objects.has(key);
+    },
+    async publicUrl(key) {
+      validateStorageKey(key);
+      const entry = objects.get(key);
+      if (!entry || entry.visibility !== "public" || !options.publicBaseUrl) {
+        return null;
+      }
+
+      return joinPublicUrl(options.publicBaseUrl, key);
+    },
+  };
+}

package/src/ports/testing.ts

@@ -0,0 +1,234 @@
+import type { EventBusPort } from "./events";
+import {
+  type CreateGateOptions,
+  createGate,
+  type GateDecision,
+  type GatePort,
+  type PolicyContextFromDefinitions,
+  type PolicyDefinition,
+  type PolicyMapFromDefinitions,
+  type PolicySubjectArgs,
+} from "./policy";
+
+/**
+ * A recorded event entry from the recording event bus.
+ */
+export interface RecordedEvent {
+  name: string;
+  payload: unknown;
+}
+
+/**
+ * Create a recording event bus for testing.
+ *
+ * This bus records all published events for later assertion,
+ * but does not support subscription (throws if called).
+ *
+ * @example
+ * ```ts
+ * const { bus, events } = createRecordingEventBus();
+ *
+ * // Inject bus into your use case
+ * await createUser({ ports: { eventBus: bus } });
+ *
+ * // Assert on recorded events
+ * expect(events).toHaveLength(1);
+ * expect(events[0].name).toBe("user.registered");
+ * expect(events[0].payload).toEqual({ userId: "123", email: "test@example.com" });
+ * ```
+ */
+export function createRecordingEventBus(): {
+  bus: EventBusPort;
+  events: RecordedEvent[];
+} {
+  const events: RecordedEvent[] = [];
+
+  const bus: EventBusPort = {
+    publish(event, payload) {
+      events.push({ name: event.name, payload });
+    },
+    subscribe() {
+      throw new Error("Not implemented for recording bus");
+    },
+  };
+
+  return { bus, events };
+}
+
+export type PolicyMatrixExpectation = "allow" | "deny";
+
+type PolicyMatrixSubject<TResolver> =
+  PolicySubjectArgs<TResolver> extends [subject: infer Subject]
+    ? { subject: Subject }
+    : { subject?: never };
+
+export type PolicyMatrixCase<
+  TContext,
+  TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[],
+> = {
+  [TAbility in keyof PolicyMapFromDefinitions<TPolicies> & string]: {
+    name: string;
+    ctx: TContext;
+    ability: TAbility;
+    expected: PolicyMatrixExpectation;
+    reason?: string;
+    code?: string;
+  } & PolicyMatrixSubject<PolicyMapFromDefinitions<TPolicies>[TAbility]>;
+}[keyof PolicyMapFromDefinitions<TPolicies> & string];
+
+export type UntypedPolicyMatrixCase<TContext> = {
+  name: string;
+  ctx: TContext;
+  ability: string;
+  subject?: unknown;
+  expected: PolicyMatrixExpectation;
+  reason?: string;
+  code?: string;
+};
+
+export type PolicyMatrixResult<
+  TContext,
+  TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[],
+> = {
+  case: PolicyMatrixCase<TContext, TPolicies>;
+  decision: GateDecision;
+  passed: boolean;
+  message?: string;
+};
+
+export type PolicyTester<
+  TContext,
+  TPolicies extends readonly PolicyDefinition[],
+> = {
+  gate: GatePort<TContext, TPolicies>;
+  evaluateMatrix(
+    cases: readonly PolicyMatrixCase<TContext, TPolicies>[],
+  ): Promise<PolicyMatrixResult<TContext, TPolicies>[]>;
+  assertMatrix(
+    cases: readonly PolicyMatrixCase<TContext, TPolicies>[],
+  ): Promise<void>;
+};
+
+export function createPolicyTester<
+  const TPolicies extends readonly PolicyDefinition[],
+>(
+  options: CreateGateOptions<
+    PolicyContextFromDefinitions<TPolicies>,
+    TPolicies
+  >,
+): PolicyTester<PolicyContextFromDefinitions<TPolicies>, TPolicies> {
+  const gate = createGate(options);
+
+  return {
+    gate,
+    evaluateMatrix: (cases) => evaluatePolicyMatrix(gate, cases),
+    assertMatrix: (cases) => assertPolicyMatrix(gate, cases),
+  };
+}
+
+export async function evaluatePolicyMatrix<
+  TContext,
+  TPolicies extends readonly PolicyDefinition[],
+>(
+  gate: GatePort<TContext, TPolicies>,
+  cases: readonly PolicyMatrixCase<TContext, TPolicies>[],
+): Promise<PolicyMatrixResult<TContext, TPolicies>[]> {
+  const results: PolicyMatrixResult<TContext, TPolicies>[] = [];
+
+  for (const matrixCase of cases) {
+    const decision = await inspectPolicyMatrixCase(gate, matrixCase);
+    const passed = policyMatrixCasePassed(matrixCase, decision);
+
+    results.push({
+      case: matrixCase,
+      decision,
+      passed,
+      message: passed
+        ? undefined
+        : policyMatrixFailureMessage(matrixCase, decision),
+    });
+  }
+
+  return results;
+}
+
+export async function assertPolicyMatrix<
+  TContext,
+  TPolicies extends readonly PolicyDefinition[],
+>(
+  gate: GatePort<TContext, TPolicies>,
+  cases: readonly PolicyMatrixCase<TContext, TPolicies>[],
+): Promise<void> {
+  const results = await evaluatePolicyMatrix(gate, cases);
+  const failures = results.filter((result) => !result.passed);
+
+  if (failures.length === 0) return;
+
+  throw new Error(
+    [
+      `Policy matrix failed for ${failures.length} case${
+        failures.length === 1 ? "" : "s"
+      }.`,
+      ...failures.map((failure) => `- ${failure.message}`),
+    ].join("\n"),
+  );
+}
+
+async function inspectPolicyMatrixCase<
+  TContext,
+  TPolicies extends readonly PolicyDefinition[],
+>(
+  gate: GatePort<TContext, TPolicies>,
+  matrixCase: PolicyMatrixCase<TContext, TPolicies>,
+): Promise<GateDecision> {
+  const inspect = gate.inspect as DynamicGateInspect<TContext>;
+
+  if ("subject" in matrixCase) {
+    return inspect(matrixCase.ctx, matrixCase.ability, matrixCase.subject);
+  }
+
+  return inspect(matrixCase.ctx, matrixCase.ability);
+}
+
+function policyMatrixCasePassed<TContext>(
+  matrixCase: UntypedPolicyMatrixCase<TContext>,
+  decision: GateDecision,
+): boolean {
+  if (matrixCase.expected === "allow" && !decision.allowed) return false;
+  if (matrixCase.expected === "deny" && decision.allowed) return false;
+  if (matrixCase.reason && decision.allowed) return false;
+  if (matrixCase.code && decision.allowed) return false;
+  if (decision.allowed) return true;
+
+  return (
+    (!matrixCase.reason || decision.reason === matrixCase.reason) &&
+    (!matrixCase.code || decision.code === matrixCase.code)
+  );
+}
+
+function policyMatrixFailureMessage<TContext>(
+  matrixCase: UntypedPolicyMatrixCase<TContext>,
+  decision: GateDecision,
+): string {
+  const expected: string[] = [matrixCase.expected];
+  if (matrixCase.reason) expected.push(`reason "${matrixCase.reason}"`);
+  if (matrixCase.code) expected.push(`code "${matrixCase.code}"`);
+
+  const actual = decision.allowed
+    ? "allow"
+    : [
+        "deny",
+        decision.reason ? `reason "${decision.reason}"` : undefined,
+        decision.code ? `code "${decision.code}"` : undefined,
+      ]
+        .filter(Boolean)
+        .join(", ");
+
+  return `${matrixCase.name}: expected ${expected.join(", ")}, received ${actual}.`;
+}
+
+type DynamicGateInspect<TContext> = (
+  ctx: TContext,
+  ability: string,
+  subject?: unknown,
+) => Promise<GateDecision>;