@beignet/core 0.0.1

package/src/ports/id-generator.ts

@@ -0,0 +1,36 @@
+export interface IdGeneratorPort {
+  nextId(): string;
+}
+
+export interface SequenceIdGeneratorPort extends IdGeneratorPort {
+  reset(next?: number): void;
+}
+
+export function createUuidIdGenerator(): IdGeneratorPort {
+  return {
+    nextId: () => {
+      if (typeof globalThis.crypto?.randomUUID !== "function") {
+        throw new Error(
+          "createUuidIdGenerator requires globalThis.crypto.randomUUID(). Provide a custom IdGeneratorPort in this runtime.",
+        );
+      }
+
+      return globalThis.crypto.randomUUID();
+    },
+  };
+}
+
+export function createSequenceIdGenerator(
+  options: { prefix?: string; start?: number } = {},
+): SequenceIdGeneratorPort {
+  const prefix = options.prefix ?? "id";
+  const start = options.start ?? 1;
+  let next = start;
+
+  return {
+    nextId: () => `${prefix}_${next++}`,
+    reset: (value = start) => {
+      next = value;
+    },
+  };
+}

package/src/ports/index.ts

@@ -0,0 +1,221 @@
+/**
+ * @beignet/core/ports
+ *
+ * A tiny, framework-agnostic subpath that standardizes how apps define and
+ * type their "ports" (outbound dependencies like db, cache, event bus).
+ *
+ * This subpath provides:
+ * - `definePorts` – helper to define a typed ports object
+ * - `PortsContext` – a generic type that describes ctx objects that carry ports
+ * - `EventBusPort` – interface for event bus implementations
+ * - `JobDispatcherPort` – interface for job dispatch implementations
+ * - `UnitOfWorkPort` – interface for app-owned transaction boundaries
+ * - `AuthPort` – interface for request authentication implementations
+ * - `AuditLogPort` – interface for audit/activity log implementations
+ * - `ClockPort` – interface for deterministic time
+ * - `IdGeneratorPort` – interface for deterministic id generation
+ * - `LoggerPort` – interface for structured application logging
+ * - `GatePort` – interface for application authorization policies
+ * - `RateLimitPort` – interface for rate limiting implementations
+ * - `CachePort` – interface for cache implementations
+ * - `StoragePort` – interface for object/file storage implementations
+ *
+ * Dedicated framework areas own their capability-specific APIs:
+ * - `@beignet/core/mail` owns `MailerPort` and mail test adapters
+ * - `@beignet/core/schedules` owns scheduled task definitions and runners
+ */
+
+/**
+ * A generic map of named "ports" (outbound dependencies) that your
+ * application depends on: db, mailer, cache, event bus, etc.
+ *
+ * This is intentionally very loose: users define the exact shape via
+ * `definePorts(...)`.
+ */
+export type AnyPorts = Record<string, unknown>;
+
+/**
+ * Define the set of ports (outbound dependencies) for your application.
+ *
+ * This is essentially a typed identity function. It:
+ * - captures the exact shape of the provided `ports` object
+ * - allows you to export `type AppPorts = typeof appPorts` in your app
+ *
+ * @example
+ * ```ts
+ * const appPorts = definePorts({
+ *   db: dbAdapter,
+ *   mailer: mailerAdapter,
+ * });
+ *
+ * export type AppPorts = typeof appPorts;
+ * ```
+ *
+ * @param ports - The ports object to define
+ * @returns The same ports object, unchanged
+ */
+export function definePorts<P extends AnyPorts>(ports: P): P {
+  return ports;
+}
+
+/**
+ * A small helper type describing a context object that carries `ports`.
+ *
+ * You typically use this to define your application context:
+ *
+ * @example
+ * ```ts
+ * import type { PortsContext } from "@beignet/core/ports";
+ * import type { AppPorts } from "./core/ports";
+ *
+ * export interface AppCtx extends PortsContext<AppPorts> {
+ *   user: { id: string } | null;
+ *   now: () => Date;
+ *   appError: AppErrorCreator<typeof errors>;
+ * }
+ * ```
+ */
+export interface PortsContext<P extends AnyPorts = AnyPorts> {
+  ports: P;
+}
+
+export type {
+  ActivityActor,
+  ActivityActorType,
+  ActivityMetadata,
+  ActivityMetadataValue,
+  ActivityResource,
+  ActivityTenant,
+  AuditLogEntry,
+  AuditLogEntryInput,
+  AuditLogOptions,
+  AuditLogPort,
+  AuditOutcome,
+  MemoryAuditLogPort,
+} from "./audit";
+export {
+  createAnonymousActor,
+  createMemoryAuditLog,
+  createRedactedAuditLog,
+  createServiceActor,
+  createSystemActor,
+  createTenant,
+  createUserActor,
+  normalizeAuditLogEntry,
+  redactAuditLogEntry,
+} from "./audit";
+export type {
+  AuthPort,
+  AuthRequestLike,
+  AuthSession,
+  StaticAuthSessionFactory,
+} from "./auth";
+export {
+  AuthUnauthorizedError,
+  createAnonymousAuth,
+  createStaticAuth,
+} from "./auth";
+// Ports builder exports
+export {
+  createPortsBuilder,
+  type PortsBuilder,
+  type PortsOf,
+} from "./builder";
+export type { CachePort, CacheSetOptions } from "./cache";
+// Cache port exports
+export { createMemoryCache } from "./cache";
+// Clock port exports
+export type { ClockPort, FrozenClockPort } from "./clock";
+export { createFrozenClock, createSystemClock } from "./clock";
+// Event bus exports
+export type {
+  DomainEventDef,
+  EventBusPort,
+  InferEventPayload,
+  InferJobPayload,
+  JobDef,
+  JobDispatcherPort,
+} from "./events";
+// Id generator port exports
+export type { IdGeneratorPort, SequenceIdGeneratorPort } from "./id-generator";
+export {
+  createSequenceIdGenerator,
+  createUuidIdGenerator,
+} from "./id-generator";
+// Logger port exports
+export type {
+  LoggerPort,
+  LogLevel,
+  MemoryLogEntry,
+  MemoryLoggerPort,
+} from "./logger";
+export { createMemoryLogger, createNoopLogger } from "./logger";
+// Policy and authorization gate exports
+export type {
+  BoundGate,
+  CreateGateOptions,
+  GateAllowedDecision,
+  GateDecision,
+  GateDeniedDecision,
+  GateDenyHandler,
+  GatePolicyResult,
+  GatePort,
+  PolicyContextFromDefinitions,
+  PolicyDefinition,
+  PolicyMapFromDefinitions,
+  PolicyResolver,
+  PolicySubjectArgs,
+} from "./policy";
+export {
+  allow,
+  createGate,
+  definePolicy,
+  deny,
+  GateAuthorizationError,
+} from "./policy";
+export type {
+  RateLimitHitOptions,
+  RateLimitPort,
+  RateLimitResult,
+} from "./rate-limit";
+// Rate limit port exports
+export { createMemoryRateLimiter } from "./rate-limit";
+// Redaction exports
+export {
+  createRedactor,
+  DEFAULT_CIRCULAR_VALUE,
+  DEFAULT_REDACTED_VALUE,
+  DEFAULT_SENSITIVE_KEY_TERMS,
+  DEFAULT_SENSITIVE_KEYS,
+  DEFAULT_TRUNCATED_VALUE,
+  isSensitiveKey,
+  type RedactableHeaders,
+  type RedactionDecisionContext,
+  type RedactionOptions,
+  type Redactor,
+  redactHeaders,
+  redactValue,
+} from "./redaction";
+// Storage port exports
+export type {
+  MemoryStorageOptions,
+  StorageBody,
+  StorageMetadata,
+  StorageObject,
+  StorageObjectBody,
+  StoragePort,
+  StoragePutOptions,
+  StorageVisibility,
+} from "./storage";
+export { createMemoryStorage } from "./storage";
+// Unit of Work exports
+export {
+  type BufferedDomainEventRecorder,
+  createDomainEventRecorder,
+  createNoopUnitOfWork,
+  type DomainEventRecorderPort,
+  type NoopUnitOfWorkOptions,
+  type RecordedDomainEvent,
+  type UnitOfWorkCallback,
+  type UnitOfWorkPort,
+} from "./unit-of-work";

package/src/ports/logger.ts

@@ -0,0 +1,67 @@
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+
+export interface LoggerPort {
+  trace(message: string, meta?: Record<string, unknown>): void;
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+  fatal(message: string, meta?: Record<string, unknown>): void;
+  child(bindings: Record<string, unknown>): LoggerPort;
+}
+
+export interface MemoryLogEntry {
+  level: LogLevel;
+  message: string;
+  meta?: Record<string, unknown>;
+  bindings: Record<string, unknown>;
+}
+
+export interface MemoryLoggerPort extends LoggerPort {
+  entries: MemoryLogEntry[];
+}
+
+export function createNoopLogger(): LoggerPort {
+  const logger: LoggerPort = {
+    trace: () => {},
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    fatal: () => {},
+    child: () => logger,
+  };
+
+  return logger;
+}
+
+export function createMemoryLogger(
+  bindings: Record<string, unknown> = {},
+  entries: MemoryLogEntry[] = [],
+): MemoryLoggerPort {
+  const capturedBindings = { ...bindings };
+  const record = (
+    level: LogLevel,
+    message: string,
+    meta?: Record<string, unknown>,
+  ) => {
+    entries.push({
+      level,
+      message,
+      meta: meta ? { ...meta } : undefined,
+      bindings: { ...capturedBindings },
+    });
+  };
+
+  return {
+    entries,
+    trace: (message, meta) => record("trace", message, meta),
+    debug: (message, meta) => record("debug", message, meta),
+    info: (message, meta) => record("info", message, meta),
+    warn: (message, meta) => record("warn", message, meta),
+    error: (message, meta) => record("error", message, meta),
+    fatal: (message, meta) => record("fatal", message, meta),
+    child: (childBindings) =>
+      createMemoryLogger({ ...capturedBindings, ...childBindings }, entries),
+  };
+}

package/src/ports/policy.ts

@@ -0,0 +1,242 @@
+type MaybePromise<T> = T | Promise<T>;
+
+export type GateAllowedDecision = {
+  allowed: true;
+};
+
+export type GateDeniedDecision = {
+  allowed: false;
+  reason?: string;
+  code?: string;
+  details?: unknown;
+};
+
+export type GateDecision = GateAllowedDecision | GateDeniedDecision;
+export type GatePolicyResult = boolean | GateDecision;
+
+export type PolicyResolver = (
+  ...args: never[]
+) => MaybePromise<GatePolicyResult>;
+
+export type PolicyDefinition<
+  TPolicies extends Record<string, PolicyResolver> = Record<
+    string,
+    PolicyResolver
+  >,
+> = {
+  policies: TPolicies;
+};
+
+export type PolicyContext<TResolver> = TResolver extends (
+  ctx: infer Ctx,
+  ...args: never[]
+) => MaybePromise<GatePolicyResult>
+  ? Ctx
+  : never;
+
+export type PolicySubjectArgs<TResolver> = TResolver extends (
+  ...args: infer TArgs
+) => MaybePromise<GatePolicyResult>
+  ? TArgs extends [unknown, infer Subject]
+    ? [subject: Subject]
+    : []
+  : [];
+
+type UnionToIntersection<T> = (
+  T extends unknown
+    ? (value: T) => void
+    : never
+) extends (value: infer U) => void
+  ? U
+  : never;
+
+export type PolicyMapFromDefinitions<
+  TPolicies extends readonly PolicyDefinition[],
+> = UnionToIntersection<
+  TPolicies[number] extends PolicyDefinition<infer TPolicyMap>
+    ? TPolicyMap
+    : never
+>;
+
+export type PolicyContextFromDefinitions<
+  TPolicies extends readonly PolicyDefinition[],
+> = PolicyContext<
+  PolicyMapFromDefinitions<TPolicies>[keyof PolicyMapFromDefinitions<TPolicies>]
+>;
+
+export type BoundGate<TPolicies extends readonly PolicyDefinition[]> = {
+  can<TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string>(
+    ability: TAbility,
+    ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
+  ): Promise<boolean>;
+  inspect<TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string>(
+    ability: TAbility,
+    ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
+  ): Promise<GateDecision>;
+  authorize<
+    TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string,
+  >(
+    ability: TAbility,
+    ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
+  ): Promise<GateAllowedDecision>;
+};
+
+export type GatePort<
+  TContext,
+  TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[],
+> = {
+  bind(ctx: TContext): BoundGate<TPolicies>;
+  can<TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string>(
+    ctx: TContext,
+    ability: TAbility,
+    ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
+  ): Promise<boolean>;
+  inspect<TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string>(
+    ctx: TContext,
+    ability: TAbility,
+    ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
+  ): Promise<GateDecision>;
+  authorize<
+    TAbility extends keyof PolicyMapFromDefinitions<TPolicies> & string,
+  >(
+    ctx: TContext,
+    ability: TAbility,
+    ...subject: PolicySubjectArgs<PolicyMapFromDefinitions<TPolicies>[TAbility]>
+  ): Promise<GateAllowedDecision>;
+};
+
+export type GateDenyHandler<TContext> = (
+  decision: GateDeniedDecision,
+  params: {
+    ctx: TContext;
+    ability: string;
+    subject?: unknown;
+  },
+) => MaybePromise<Error | undefined>;
+
+export type CreateGateOptions<
+  TContext,
+  TPolicies extends readonly PolicyDefinition[],
+> = {
+  policies: TPolicies;
+  onDeny?: GateDenyHandler<TContext>;
+};
+
+export class GateAuthorizationError extends Error {
+  readonly code: string;
+  readonly status = 403;
+  readonly details?: unknown;
+
+  constructor(decision: GateDeniedDecision = deny()) {
+    super(decision.reason ?? "Forbidden");
+    this.name = "GateAuthorizationError";
+    this.code = decision.code ?? "FORBIDDEN";
+    this.details = decision.details;
+  }
+}
+
+export function allow(): GateAllowedDecision {
+  return { allowed: true };
+}
+
+export function deny(
+  reasonOrDecision?: string | Omit<GateDeniedDecision, "allowed">,
+): GateDeniedDecision {
+  if (typeof reasonOrDecision === "string") {
+    return { allowed: false, reason: reasonOrDecision };
+  }
+
+  return {
+    allowed: false,
+    ...reasonOrDecision,
+  };
+}
+
+export function definePolicy<
+  const TPolicies extends Record<string, PolicyResolver>,
+>(policies: TPolicies): PolicyDefinition<TPolicies> {
+  return { policies };
+}
+
+export function createGate<
+  TContext,
+  const TPolicies extends readonly PolicyDefinition[],
+>(
+  options: CreateGateOptions<TContext, TPolicies>,
+): GatePort<TContext, TPolicies> {
+  const registry = new Map<string, PolicyResolver>();
+
+  for (const definition of options.policies) {
+    for (const [ability, resolver] of Object.entries(definition.policies)) {
+      if (registry.has(ability)) {
+        throw new Error(`Policy ability "${ability}" is already registered.`);
+      }
+
+      registry.set(ability, resolver);
+    }
+  }
+
+  async function inspect(
+    ctx: TContext,
+    ability: string,
+    subject?: unknown,
+  ): Promise<GateDecision> {
+    const resolver = registry.get(ability);
+    if (!resolver) {
+      return deny({
+        reason: `No policy registered for "${ability}".`,
+        code: "POLICY_NOT_FOUND",
+      });
+    }
+
+    const result = await resolver(ctx as never, subject as never);
+    return normalizeDecision(result);
+  }
+
+  async function authorize(
+    ctx: TContext,
+    ability: string,
+    subject?: unknown,
+  ): Promise<GateAllowedDecision> {
+    const decision = await inspect(ctx, ability, subject);
+    if (decision.allowed) return decision;
+
+    const thrown = await options.onDeny?.(decision, { ctx, ability, subject });
+    throw thrown ?? new GateAuthorizationError(decision);
+  }
+
+  function bind(ctx: TContext): BoundGate<TPolicies> {
+    return {
+      can: async (ability, ...subject) => gate.can(ctx, ability, ...subject),
+      inspect: async (ability, ...subject) =>
+        gate.inspect(ctx, ability, ...subject),
+      authorize: async (ability, ...subject) =>
+        gate.authorize(ctx, ability, ...subject),
+    };
+  }
+
+  const gate: GatePort<TContext, TPolicies> = {
+    bind,
+    async can(ctx, ability, ...subject) {
+      return (await inspect(ctx, ability, firstSubject(subject))).allowed;
+    },
+    inspect: async (ctx, ability, ...subject) =>
+      inspect(ctx, ability, firstSubject(subject)),
+    authorize: async (ctx, ability, ...subject) =>
+      authorize(ctx, ability, firstSubject(subject)),
+  };
+
+  return gate;
+}
+
+function normalizeDecision(result: GatePolicyResult): GateDecision {
+  if (typeof result === "boolean") {
+    return result ? allow() : deny();
+  }
+
+  return result;
+}
+
+function firstSubject(subject: readonly unknown[]): unknown {
+  return subject[0];
+}

package/src/ports/rate-limit.ts

@@ -0,0 +1,91 @@
+export interface RateLimitHitOptions {
+  /**
+   * Unique key for this rate limit window.
+   *
+   * Examples: "global", "ip:203.0.113.10", "user:123".
+   */
+  key: string;
+  /**
+   * Maximum allowed hits inside the window.
+   */
+  limit: number;
+  /**
+   * Length of the window in seconds.
+   */
+  windowSec: number;
+}
+
+export interface RateLimitResult {
+  /**
+   * True when the hit is within the configured limit.
+   */
+  allowed: boolean;
+  /**
+   * Remaining allowed hits in the window, if known. May be null if the
+   * implementation does not track it.
+   */
+  remaining: number | null;
+  /**
+   * Date when the window resets, if known. May be null.
+   */
+  resetAt: Date | null;
+  /**
+   * Seconds until the caller should retry, if the hit was rejected and the
+   * implementation can calculate it.
+   */
+  retryAfterSeconds: number | null;
+}
+
+export interface RateLimitPort {
+  hit(options: RateLimitHitOptions): Promise<RateLimitResult>;
+}
+
+type MemoryRateLimitWindow = {
+  count: number;
+  resetAt: number;
+};
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+}
+
+function toRetryAfterSeconds(resetAt: number): number {
+  return Math.max(0, Math.ceil((resetAt - Date.now()) / 1000));
+}
+
+export function createMemoryRateLimiter(): RateLimitPort {
+  const windows = new Map<string, MemoryRateLimitWindow>();
+
+  return {
+    async hit({ key, limit, windowSec }) {
+      assertPositiveInteger("limit", limit);
+      assertPositiveInteger("windowSec", windowSec);
+
+      const now = Date.now();
+      const current = windows.get(key);
+      const window =
+        current && current.resetAt > now
+          ? current
+          : {
+              count: 0,
+              resetAt: now + windowSec * 1000,
+            };
+
+      window.count += 1;
+      windows.set(key, window);
+
+      const allowed = window.count <= limit;
+      const remaining = Math.max(0, limit - window.count);
+      const resetAt = new Date(window.resetAt);
+
+      return {
+        allowed,
+        remaining,
+        resetAt,
+        retryAfterSeconds: allowed ? null : toRetryAfterSeconds(window.resetAt),
+      };
+    },
+  };
+}