@beignet/core 0.0.2 → 0.0.4

package/src/ports/audit.ts

@@ -1,4 +1,8 @@
-import { redactValue } from "./redaction";
+import {
+  type ProviderInstrumentationTarget,
+  resolveProviderInstrumentationPort,
+} from "../providers/instrumentation.js";
+import { redactValue } from "./redaction.js";
 
 /**
  * The normalized category of actor that caused application activity.
@@ -111,10 +115,11 @@ export interface ActivityResource {
 /**
  * A normalized audit/activity log entry.
  *
- * Application code usually creates these through an app-owned helper such as
- * `auditEntry(ctx, { action, resource })` so actor, tenant, request ID, and
- * trace ID are copied from context consistently. Durability depends on the
- * `AuditLogPort` implementation.
+ * Application code usually records entries through an audit port wrapped with
+ * `createAmbientAuditLog(...)` from `@beignet/core/server`, which fills
+ * missing actor, tenant, request ID, and trace ID fields from the ambient
+ * request context at record time. Durability depends on the `AuditLogPort`
+ * implementation.
  */
 export interface AuditLogEntry {
   /**
@@ -165,14 +170,18 @@ export interface AuditLogEntry {
 /**
  * Input accepted by `AuditLogPort.record(...)`.
  *
- * `occurredAt` and `outcome` are optional at call sites. Adapters that store
- * audit entries should call `normalizeAuditLogEntry(...)` before persistence or
- * otherwise apply equivalent defaults.
+ * `actor`, `occurredAt`, and `outcome` are optional at call sites. Wrappers
+ * such as `createAmbientAuditLog(...)` fill a missing actor from the ambient
+ * request context. Adapters that store audit entries should call
+ * `normalizeAuditLogEntry(...)` before persistence or otherwise apply
+ * equivalent defaults; entries without an actor normalize to an anonymous
+ * actor.
  */
 export type AuditLogEntryInput = Omit<
   AuditLogEntry,
-  "occurredAt" | "outcome"
+  "actor" | "occurredAt" | "outcome"
 > & {
+  actor?: ActivityActor;
   occurredAt?: Date;
   outcome?: AuditOutcome;
 };
@@ -259,7 +268,7 @@ export function createServiceActor(
 /**
  * Create a system actor descriptor for framework or app-owned background work.
  *
- * Use this for scheduled tasks, scripts, maintenance jobs, and other work that
+ * Use this for schedules, scripts, maintenance jobs, and other work that
  * is not directly caused by a user or external service.
  *
  * @example
@@ -334,13 +343,15 @@ export function createTenant(
  * Fill default audit fields for an input entry.
  *
  * @param entry - Partial audit entry accepted by `AuditLogPort.record(...)`.
- * @returns A complete audit entry with `occurredAt` and `outcome` populated.
+ * @returns A complete audit entry with `actor`, `occurredAt`, and `outcome`
+ * populated. Entries without an actor default to an anonymous actor.
  */
 export function normalizeAuditLogEntry(
   entry: AuditLogEntryInput,
 ): AuditLogEntry {
   return {
     ...entry,
+    actor: entry.actor ?? createAnonymousActor(),
     occurredAt: entry.occurredAt ?? new Date(),
     outcome: entry.outcome ?? "success",
   };
@@ -409,6 +420,104 @@ export function createRedactedAuditLog(
   };
 }
 
+/**
+ * Options for wrapping an audit log with instrumentation emission.
+ */
+export interface InstrumentedAuditLogOptions {
+  /**
+   * Durable audit log to write first.
+   */
+  audit: AuditLogPort;
+  /**
+   * Instrumentation sink, port, or ports object. Pass the app ports object so
+   * the sink (`ports.instrumentation`, then `ports.devtools`) is resolved
+   * lazily on each write and observes provider startup order.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
+  /**
+   * Whether to emit instrumentation events. Defaults to true.
+   */
+  emit?: boolean;
+  /**
+   * Optional app-owned redactor applied after Beignet's audit redaction.
+   */
+  redact?: (entry: AuditLogEntry) => AuditLogEntry;
+}
+
+function prepareInstrumentedEntry(
+  input: AuditLogEntryInput,
+  redact?: (entry: AuditLogEntry) => AuditLogEntry,
+): AuditLogEntry {
+  const redacted = redactAuditLogEntry(normalizeAuditLogEntry(input));
+  return redact ? redact(redacted) : redacted;
+}
+
+function auditSummary(entry: AuditLogEntry): string {
+  const resource = entry.resource?.id
+    ? `${entry.resource.type}:${entry.resource.id}`
+    : entry.resource?.type;
+  const outcome = entry.outcome === "failure" ? "failed" : "succeeded";
+  return resource
+    ? `${entry.action} ${outcome} for ${resource}`
+    : `${entry.action} ${outcome}`;
+}
+
+/**
+ * Wrap an audit log so durable audit writes also appear in instrumentation
+ * sinks such as devtools.
+ *
+ * Instrumentation failures are ignored so audit persistence remains the
+ * source of truth.
+ *
+ * @example
+ * ```ts
+ * const audit = createInstrumentedAuditLog({
+ *   audit: createDrizzleAuditLog(db),
+ *   instrumentation: ports,
+ * });
+ * ```
+ */
+export function createInstrumentedAuditLog(
+  options: InstrumentedAuditLogOptions,
+): AuditLogPort {
+  return {
+    async record(input) {
+      const entry = prepareInstrumentedEntry(input, options.redact);
+
+      await options.audit.record(entry);
+
+      if (options.emit === false) return;
+
+      const port = resolveProviderInstrumentationPort(options.instrumentation);
+      if (!port) return;
+
+      try {
+        port.record({
+          type: "custom",
+          watcher: "audit",
+          name: entry.action,
+          label: "Audit",
+          summary: auditSummary(entry),
+          requestId: entry.requestId,
+          traceId: entry.traceId,
+          details: {
+            action: entry.action,
+            actor: entry.actor,
+            tenant: entry.tenant,
+            resource: entry.resource,
+            outcome: entry.outcome,
+            message: entry.message,
+            metadata: entry.metadata,
+            occurredAt: entry.occurredAt.toISOString(),
+          },
+        });
+      } catch {
+        // Instrumentation is an observer; durable audit writes must not depend on it.
+      }
+    },
+  };
+}
+
 /**
  * Create an in-memory audit log for tests and local examples.
  *

package/src/ports/auth.ts

@@ -1,3 +1,5 @@
+import type { ActivityTenant } from "./audit.js";
+
 /**
  * Minimal request shape consumed by Beignet auth ports.
  *
@@ -41,6 +43,136 @@ export class AuthUnauthorizedError extends Error {
   }
 }
 
+/**
+ * Error thrown by tenant helpers when a workflow requires a tenant scope but
+ * the current context has none.
+ *
+ * The server maps this to a framework-owned 403 response, mirroring how
+ * `AuthUnauthorizedError` maps to a framework-owned 401.
+ */
+export class TenantRequiredError extends Error {
+  readonly code = "TENANT_REQUIRED";
+  readonly status = 403;
+
+  constructor(message = "A tenant is required for this action.") {
+    super(message);
+    this.name = "TenantRequiredError";
+  }
+}
+
+/**
+ * Options accepted by the `requireX(ctx)` context helpers.
+ */
+export interface RequireOptions {
+  /**
+   * Create the error to throw instead of the framework default.
+   */
+  error?: () => unknown;
+}
+
+function throwRequired(
+  options: RequireOptions | undefined,
+  fallback: () => Error,
+): never {
+  throw options?.error ? options.error() : fallback();
+}
+
+/**
+ * Return the authenticated session from `ctx.auth` or throw.
+ *
+ * Throws `AuthUnauthorizedError` (a framework-owned 401) by default. Pass
+ * `options.error` to throw an app-owned error instead.
+ *
+ * @example
+ * ```ts
+ * const session = requireSession(ctx);
+ * ```
+ */
+export function requireSession<Session extends AuthSession>(
+  ctx: { auth?: Session | null },
+  options?: RequireOptions,
+): Session {
+  if (!ctx.auth) {
+    throwRequired(options, () => new AuthUnauthorizedError());
+  }
+
+  return ctx.auth;
+}
+
+/**
+ * Return the authenticated user from `ctx.auth` or throw.
+ *
+ * The user type is inferred from the app's `ctx.auth` session. Throws
+ * `AuthUnauthorizedError` (a framework-owned 401) by default.
+ *
+ * @example
+ * ```ts
+ * const user = requireUser(ctx);
+ * ```
+ */
+export function requireUser<User>(
+  ctx: { auth?: AuthSession<User> | null },
+  options?: RequireOptions,
+): User {
+  return requireSession(ctx, options).user;
+}
+
+/**
+ * Return the authenticated user's ID from `ctx.auth` or throw.
+ *
+ * Throws `AuthUnauthorizedError` (a framework-owned 401) by default.
+ *
+ * @example
+ * ```ts
+ * const userId = requireUserId(ctx);
+ * ```
+ */
+export function requireUserId(
+  ctx: { auth?: AuthSession<{ id: string }> | null },
+  options?: RequireOptions,
+): string {
+  return requireUser(ctx, options).id;
+}
+
+/**
+ * Return the tenant scope from `ctx.tenant` or throw.
+ *
+ * Throws `TenantRequiredError` (a framework-owned 403) by default. Pass
+ * `options.error` to throw an app-owned error instead.
+ *
+ * @example
+ * ```ts
+ * const tenant = requireTenant(ctx);
+ * ```
+ */
+export function requireTenant(
+  ctx: { tenant?: ActivityTenant | null },
+  options?: RequireOptions,
+): ActivityTenant {
+  if (!ctx.tenant) {
+    throwRequired(options, () => new TenantRequiredError());
+  }
+
+  return ctx.tenant;
+}
+
+/**
+ * Return the tenant ID from `ctx.tenant` or throw.
+ *
+ * Throws `TenantRequiredError` (a framework-owned 403) by default.
+ *
+ * @example
+ * ```ts
+ * const tenantId = requireTenantId(ctx);
+ * ```
+ */
+export function requireTenantId(
+  ctx: { tenant?: ActivityTenant | null },
+  options?: RequireOptions,
+): string {
+  return requireTenant(ctx, options).id;
+}
+
 /**
  * App-facing authentication port.
  *

package/src/ports/events.ts

@@ -2,11 +2,11 @@ import type {
   EventPayloadDef,
   InferEventPayload as InferContractEventPayload,
   StandardSchema,
-} from "../events";
+} from "../events/index.js";
 import type {
   JobDef as ContractJobDef,
   InferJobPayload as InferContractJobPayload,
-} from "../jobs";
+} from "../jobs/index.js";
 
 /**
  * Represents a defined Domain Event with name and payload schema.

package/src/ports/index.ts

@@ -27,9 +27,11 @@
  * - `@beignet/core/mail` owns `MailerPort` and mail test adapters
  * - `@beignet/core/notifications` owns notification helpers and test adapters
  * - `@beignet/core/outbox` owns durable outbox helpers and test adapters
- * - `@beignet/core/schedules` owns scheduled task definitions and runners
+ * - `@beignet/core/schedules` owns schedule definitions and runners
  */
 
+import { createUnboundPort } from "./unbound.js";
+
 /**
  * A generic map of named "ports" (outbound dependencies) that your
  * application depends on: db, mailer, cache, event bus, etc.
@@ -39,28 +41,78 @@
  */
 export type AnyPorts = Record<string, unknown>;
 
+/**
+ * Definition accepted by the curried `definePorts<P>()(...)` form.
+ */
+export type DeferredPortsDefinition<
+  P extends AnyPorts,
+  Deferred extends readonly (keyof P & string)[],
+> = {
+  /**
+   * Ports the app binds directly. Optional keys of `P` may be omitted here
+   * and contributed by providers instead.
+   */
+  bound: Omit<P, Deferred[number]>;
+  /**
+   * Port keys that providers contribute during server startup. Deferred keys
+   * boot as throwing placeholders; `createServer(...)` fails startup if any
+   * are still unbound after providers have started (see `onUnboundPorts`).
+   */
+  deferred: Deferred;
+};
+
 /**
  * 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
+ * The identity form captures the exact shape of the provided `ports` object
+ * so you can export `type AppPorts = typeof appPorts`.
+ *
+ * The curried form, `definePorts<AppPorts>()({ bound, deferred })`, declares
+ * which port keys providers contribute at server startup. Deferred keys boot
+ * as throwing placeholders instead of hand-written stubs, and
+ * `createServer(...)` validates after provider startup that nothing is left
+ * unbound. Optional keys of `AppPorts` may go in either bucket.
  *
  * @example
  * ```ts
+ * // Identity form: every port is bound directly.
  * 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
+ * // Deferred form: providers contribute the rest at startup.
+ * export const appPorts = definePorts<AppPorts>()({
+ *   bound: { gate },
+ *   deferred: ["db", "mailer", "storage"],
+ * });
+ * ```
  */
-export function definePorts<P extends AnyPorts>(ports: P): P {
-  return ports;
+export function definePorts<P extends AnyPorts>(ports: P): P;
+export function definePorts<P extends AnyPorts>(): <
+  const Deferred extends readonly (keyof P & string)[],
+>(
+  definition: DeferredPortsDefinition<P, Deferred>,
+) => P;
+export function definePorts<P extends AnyPorts>(
+  ports?: P,
+):
+  | P
+  | ((
+      definition: DeferredPortsDefinition<P, readonly (keyof P & string)[]>,
+    ) => P) {
+  if (ports !== undefined) {
+    return ports;
+  }
+
+  return (definition) => {
+    const result: AnyPorts = { ...(definition.bound as AnyPorts) };
+    for (const key of definition.deferred) {
+      result[key] = createUnboundPort(key);
+    }
+    return result as P;
+  };
 }
 
 /**
@@ -93,7 +145,7 @@ export type {
   IdempotencyPort,
   IdempotencyReservation,
   IdempotencyReserveInput,
-} from "../idempotency";
+} from "../idempotency/index.js";
 /**
  * Notification port exports.
  */
@@ -104,7 +156,7 @@ export type {
   NotificationPort,
   SendNotificationOptions,
   SendNotificationResult,
-} from "../notifications";
+} from "../notifications/index.js";
 /**
  * Transactional outbox port exports.
  */
@@ -118,7 +170,7 @@ export type {
   OutboxMessageKind,
   OutboxMessageStatus,
   OutboxPort,
-} from "../outbox";
+} from "../outbox/index.js";
 /**
  * Audit log port exports.
  */
@@ -134,13 +186,15 @@ export type {
   AuditLogOptions,
   AuditLogPort,
   AuditOutcome,
+  InstrumentedAuditLogOptions,
   MemoryAuditLogPort,
-} from "./audit";
+} from "./audit.js";
 /**
  * Audit log helper exports.
  */
 export {
   createAnonymousActor,
+  createInstrumentedAuditLog,
   createMemoryAuditLog,
   createRedactedAuditLog,
   createServiceActor,
@@ -149,7 +203,7 @@ export {
   createUserActor,
   normalizeAuditLogEntry,
   redactAuditLogEntry,
-} from "./audit";
+} from "./audit.js";
 /**
  * Auth port exports.
  */
@@ -157,8 +211,9 @@ export type {
   AuthPort,
   AuthRequestLike,
   AuthSession,
+  RequireOptions,
   StaticAuthSessionFactory,
-} from "./auth";
+} from "./auth.js";
 /**
  * Auth helper exports.
  */
@@ -166,7 +221,13 @@ export {
   AuthUnauthorizedError,
   createAnonymousAuth,
   createStaticAuth,
-} from "./auth";
+  requireSession,
+  requireTenant,
+  requireTenantId,
+  requireUser,
+  requireUserId,
+  TenantRequiredError,
+} from "./auth.js";
 /**
  * Ports builder exports.
  */
@@ -174,23 +235,23 @@ export {
   createPortsBuilder,
   type PortsBuilder,
   type PortsOf,
-} from "./builder";
+} from "./builder.js";
 /**
  * Cache port exports.
  */
-export type { CachePort, CacheSetOptions } from "./cache";
+export type { CachePort, CacheSetOptions } from "./cache.js";
 /**
  * Cache helper exports.
  */
-export { createMemoryCache } from "./cache";
+export { createMemoryCache } from "./cache.js";
 /**
  * Clock port exports.
  */
-export type { ClockPort, FrozenClockPort } from "./clock";
+export type { ClockPort, FrozenClockPort } from "./clock.js";
 /**
  * Clock helper exports.
  */
-export { createFrozenClock, createSystemClock } from "./clock";
+export { createFrozenClock, createSystemClock } from "./clock.js";
 /**
  * Event bus and job dispatcher port exports.
  */
@@ -201,18 +262,21 @@ export type {
   InferJobPayload,
   JobDef,
   JobDispatcherPort,
-} from "./events";
+} from "./events.js";
 /**
  * ID generator port exports.
  */
-export type { IdGeneratorPort, SequenceIdGeneratorPort } from "./id-generator";
+export type {
+  IdGeneratorPort,
+  SequenceIdGeneratorPort,
+} from "./id-generator.js";
 /**
  * ID generator helper exports.
  */
 export {
   createSequenceIdGenerator,
   createUuidIdGenerator,
-} from "./id-generator";
+} from "./id-generator.js";
 /**
  * Logger port exports.
  */
@@ -221,11 +285,11 @@ export type {
   LogLevel,
   MemoryLogEntry,
   MemoryLoggerPort,
-} from "./logger";
+} from "./logger.js";
 /**
  * Logger helper exports.
  */
-export { createMemoryLogger, createNoopLogger } from "./logger";
+export { createMemoryLogger, createNoopLogger } from "./logger.js";
 /**
  * Policy and authorization gate type exports.
  */
@@ -233,6 +297,7 @@ export type {
   BoundGate,
   CreateGateOptions,
   GateAllowedDecision,
+  GateContext,
   GateDecision,
   GateDeniedDecision,
   GateDenyHandler,
@@ -243,7 +308,7 @@ export type {
   PolicyMapFromDefinitions,
   PolicyResolver,
   PolicySubjectArgs,
-} from "./policy";
+} from "./policy.js";
 /**
  * Policy and authorization gate helper exports.
  */
@@ -253,7 +318,7 @@ export {
   definePolicy,
   deny,
   GateAuthorizationError,
-} from "./policy";
+} from "./policy.js";
 /**
  * Rate limit port exports.
  */
@@ -261,11 +326,11 @@ export type {
   RateLimitHitOptions,
   RateLimitPort,
   RateLimitResult,
-} from "./rate-limit";
+} from "./rate-limit.js";
 /**
  * Rate limit helper exports.
  */
-export { createMemoryRateLimiter } from "./rate-limit";
+export { createMemoryRateLimiter } from "./rate-limit.js";
 /**
  * Redaction helper exports.
  */
@@ -283,7 +348,7 @@ export {
   type Redactor,
   redactHeaders,
   redactValue,
-} from "./redaction";
+} from "./redaction.js";
 /**
  * Storage port exports.
  */
@@ -296,11 +361,15 @@ export type {
   StoragePort,
   StoragePutOptions,
   StorageVisibility,
-} from "./storage";
+} from "./storage.js";
 /**
  * Storage helper exports.
  */
-export { createMemoryStorage } from "./storage";
+export { createMemoryStorage } from "./storage.js";
+/**
+ * Unbound (deferred) port helper exports.
+ */
+export { createUnboundPort, isUnboundPort } from "./unbound.js";
 /**
  * Unit of Work port exports.
  */
@@ -313,4 +382,4 @@ export {
   type RecordedDomainEvent,
   type UnitOfWorkCallback,
   type UnitOfWorkPort,
-} from "./unit-of-work";
+} from "./unit-of-work.js";