@beignet/core 0.0.3 → 0.0.4

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";

package/src/ports/policy.ts

@@ -113,6 +113,12 @@ export type PolicyContextFromDefinitions<
  * into every authorization call.
  */
 export type BoundGate<TPolicies extends readonly PolicyDefinition[]> = {
+  /**
+   * Type-only marker that keeps `TPolicies` inferable from a bound gate.
+   * Runtime bound gates never implement this method. Method syntax keeps the
+   * marker bivariant so readonly and mutable policy tuples stay compatible.
+   */
+  __policies?(policies: TPolicies): void;
   /**
    * Return only whether the ability is allowed.
    */
@@ -138,6 +144,18 @@ export type BoundGate<TPolicies extends readonly PolicyDefinition[]> = {
   ): Promise<GateAllowedDecision>;
 };
 
+/**
+ * Context shape contributed by `gate.attach(...)`.
+ */
+export type GateContext<
+  TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[],
+> = {
+  /**
+   * Gate bound to the context that carries it.
+   */
+  gate: BoundGate<TPolicies>;
+};
+
 /**
  * App-facing authorization gate.
  *
@@ -150,9 +168,23 @@ export type GatePort<
   TPolicies extends readonly PolicyDefinition[] = readonly PolicyDefinition[],
 > = {
   /**
-   * Bind this gate to a context, usually during `createContext`.
+   * Bind this gate to a fixed context snapshot.
+   *
+   * This is the low-level primitive: the returned gate keeps evaluating
+   * against the exact object it was bound to. Prefer `attach(...)` for app
+   * context assembly so identity changes can never go stale.
    */
   bind(ctx: TContext): BoundGate<TPolicies>;
+  /**
+   * Attach a live `gate` property to a context object.
+   *
+   * The gate is exposed through a getter that re-binds against the receiving
+   * object on every access, so in-place updates to fields such as `actor` or
+   * `tenant` are always observed. The property is non-enumerable on purpose:
+   * spreading the context (`{ ...ctx }`) drops the gate instead of silently
+   * carrying a stale identity, and the next `ctx.gate` access fails loudly.
+   */
+  attach<C extends TContext & object>(ctx: C): C & GateContext<TPolicies>;
   /**
    * Return only whether the ability is allowed for a context.
    */
@@ -284,8 +316,8 @@ export function definePolicy<
 /**
  * Create an authorization gate from app-owned policy definitions.
  *
- * Register the gate as a port, then bind it to the request/background context:
- * `gate: ports.gate.bind(context)`. Use cases can then call
+ * Register the gate as a port, then let the server context blueprint attach
+ * it: `context: { gate: (ports) => ports.gate, ... }`. Use cases can then call
  * `ctx.gate.authorize(...)` for business authorization.
  *
  * @param options - Policy definitions and optional denial mapper.
@@ -348,8 +380,23 @@ export function createGate<
     };
   }
 
+  function attach<C extends TContext & object>(
+    ctx: C,
+  ): C & GateContext<TPolicies> {
+    Object.defineProperty(ctx, "gate", {
+      configurable: true,
+      enumerable: false,
+      get(this: TContext) {
+        return bind(this);
+      },
+    });
+
+    return ctx as C & GateContext<TPolicies>;
+  }
+
   const gate: GatePort<TContext, TPolicies> = {
     bind,
+    attach,
     async can(ctx, ability, ...subject) {
       return (await inspect(ctx, ability, firstSubject(subject))).allowed;
     },