@beignet/core 0.0.2 → 0.0.4

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;
     },