okengine 0.4.3 → 0.5.1

package/src/elements/gate/config.ts

@@ -0,0 +1,69 @@
+/**
+ * `oke({ gate })` — nested Gate bag (auth · policies · rate · posture).
+ */
+
+import { resolveGateAuth, type GateAuthOptions, type ResolvedGateAuth } from "../../auth/config.ts";
+import type { GateDecl } from "./declare.ts";
+
+/** Rate-limit defaults under Gate. */
+export interface GateRateLimitOptions {
+  /** When true, auth Flows attach stricter rate presets (default true when auth enabled). */
+  readonly enabled?: boolean;
+}
+
+/**
+ * Nested Gate options for {@link oke}.
+ *
+ * Replaces root `auth` / `gates` / `unguardedHttp`.
+ */
+export interface GateOptions {
+  /** Builtin hybrid-session auth + core Flows under `basePath`. */
+  readonly auth?: GateAuthOptions;
+  /** Named policy / rate declarations for the Gate runtime. */
+  readonly policies?: readonly GateDecl[];
+  /** Global rate-limit posture (auth path presets). */
+  readonly rateLimit?: GateRateLimitOptions;
+  /**
+   * HTTP auth-posture enforcement at boot.
+   * Default `"deny"`. `"allow"` is honoured only when `env === "test"`.
+   */
+  readonly unguardedHttp?: "deny" | "allow";
+}
+
+/** Fully resolved Gate config consumed by `oke` / boot. */
+export interface ResolvedGateConfig {
+  readonly auth: ResolvedGateAuth | undefined;
+  readonly policies: readonly GateDecl[];
+  readonly rateLimitEnabled: boolean;
+  readonly unguardedHttp: "deny" | "allow";
+}
+
+/** Options for {@link resolveGateConfig}. */
+export interface ResolveGateConfigOptions {
+  readonly gate?: GateOptions;
+  readonly env?: string;
+}
+
+/**
+ * Resolve the nested `gate` bag for construction / boot.
+ *
+ * @param options - Gate bag + env (for auth secret rules)
+ */
+export function resolveGateConfig(options: ResolveGateConfigOptions = {}): ResolvedGateConfig {
+  const bag = options.gate ?? {};
+  const auth =
+    bag.auth !== undefined ? resolveGateAuth({ auth: bag.auth, env: options.env }) : undefined;
+  const rateLimitEnabled =
+    bag.rateLimit?.enabled !== undefined
+      ? bag.rateLimit.enabled
+      : auth !== undefined
+        ? true
+        : false;
+
+  return {
+    auth,
+    policies: bag.policies ?? [],
+    rateLimitEnabled,
+    unguardedHttp: bag.unguardedHttp ?? "deny",
+  };
+}

package/src/elements/gate/declare.ts

@@ -63,6 +63,11 @@ export interface PolicyGateDecl {
   readonly name: string;
   readonly check: (ctx: GatePolicyContext) => boolean | Promise<boolean>;
   readonly description?: string;
+  /**
+   * Scope strings this policy requires (set by {@link GateNamespace.scope}).
+   * Same string is the policy id and the scope checked on `auth.scopes`.
+   */
+  readonly scopes?: readonly string[];
 }
 
 /** Rate gate declaration. */
@@ -94,6 +99,19 @@ export interface GateNamespace {
     name: string,
     checkOrOptions: ((ctx: GatePolicyContext) => boolean | Promise<boolean>) | PolicyGateOptions,
   ): PolicyGateDecl;
+  /**
+   * Shorthand for a scope check — single source of truth for the scope string.
+   *
+   * Equivalent to `gate.policy(name, ({ auth }) => auth.scopes.has(name))`.
+   *
+   * @param name - Scope id (also the policy name / Module:Action when it contains `:`)
+   */
+  scope(name: string): PolicyGateDecl;
+  /**
+   * Explicit public sentinel — intentionally unauthenticated HTTP surface.
+   * Counts as declared auth posture for boot (see gate boot audit).
+   */
+  readonly public: PolicyGateDecl;
   /**
    * Declare a rate limit (atomic Lua on the kv driver).
    *
@@ -102,8 +120,11 @@ export interface GateNamespace {
   rate(options: RateOptions): RateGateDecl;
 }
 
+/** Reserved policy name for {@link gate.public}. */
+export const GATE_PUBLIC_NAME = "public";
+
 /**
- * Gate element namespace — `gate.policy` · `gate.rate`.
+ * Gate element namespace — `gate.policy` · `gate.scope` · `gate.public` · `gate.rate`.
  */
 export const gate: GateNamespace = {
   /**
@@ -116,6 +137,11 @@ export const gate: GateNamespace = {
     name: string,
     checkOrOptions: ((ctx: GatePolicyContext) => boolean | Promise<boolean>) | PolicyGateOptions,
   ): PolicyGateDecl {
+    if (name === GATE_PUBLIC_NAME) {
+      throw new TypeError(
+        'gate.policy: name "public" is reserved — use gate.public for intentionally unauthenticated surfaces',
+      );
+    }
     if (typeof checkOrOptions === "function") {
       return { kind: "policy", name, check: checkOrOptions };
     }
@@ -129,6 +155,30 @@ export const gate: GateNamespace = {
     };
   },
 
+  /**
+   * Shorthand for a scope check — single source of truth for the scope string.
+   *
+   * @param name - Scope id (also the policy name)
+   */
+  scope(name: string): PolicyGateDecl {
+    if (name === GATE_PUBLIC_NAME) {
+      throw new TypeError('gate.scope: name "public" is reserved — use gate.public');
+    }
+    return {
+      kind: "policy",
+      name,
+      check: ({ auth }) => auth.scopes.has(name),
+      scopes: [name],
+    };
+  },
+
+  public: {
+    kind: "policy",
+    name: GATE_PUBLIC_NAME,
+    check: () => true,
+    description: "Intentionally unauthenticated (public) surface",
+  },
+
   /**
    * Declare a rate limit (atomic Lua on the kv driver).
    *

package/src/elements/gate/runtime.ts

@@ -3,7 +3,7 @@
  */
 
 import { parseDurationMs } from "../clock/duration.ts";
-import type { GateDecl, GatePolicyContext, RateGateDecl } from "./declare.ts";
+import { gate, type GateDecl, type GatePolicyContext, type RateGateDecl } from "./declare.ts";
 import { takeRate } from "./strategies.ts";
 
 /** KV surface required for rate gates. */
@@ -58,6 +58,8 @@ export interface GateRuntime {
  */
 export function createGateRuntime(options: CreateGateRuntimeOptions = {}): GateRuntime {
   const map = new Map<string, GateDecl>();
+  // Built-in sentinel — `.gate(gate.public)` works without listing it in `oke({ gates })`.
+  map.set(gate.public.name, gate.public);
   for (const g of options.gates ?? []) {
     map.set(g.name, g);
   }

package/src/elements/gate.test.ts

@@ -11,10 +11,12 @@ import { createRedisFakeClient, redisDriver } from "../drivers/redis.ts";
 import type { Manifest } from "../manifest/types.ts";
 import {
   ALL_RATE_STRATEGIES,
+  assertHttpGatePosture,
   createGateRuntime,
   deriveModuleActions,
   formatGatesList,
   gate,
+  GateBootError,
   takeRate,
 } from "./gate.ts";
 
@@ -35,6 +37,37 @@ describe("gate declaration", () => {
     expect(fair.strategy).toBe("sliding-window-counter");
   });
 
+  test("scope is sugar over policy with auth.scopes.has(name)", async () => {
+    const canBook = gate.scope("booking:create");
+    expect(canBook.kind).toBe("policy");
+    expect(canBook.name).toBe("booking:create");
+    expect(canBook.scopes).toEqual(["booking:create"]);
+    expect(
+      await canBook.check({
+        auth: { userId: "u1", scopes: new Set(["booking:create"]), verified: true },
+        operator: { id: null },
+      }),
+    ).toBe(true);
+    expect(
+      await canBook.check({
+        auth: { userId: "u1", scopes: new Set(), verified: true },
+        operator: { id: null },
+      }),
+    ).toBe(false);
+  });
+
+  test("public sentinel always allows and reserves the name", async () => {
+    expect(gate.public.name).toBe("public");
+    expect(
+      await gate.public.check({
+        auth: { userId: null, scopes: new Set() },
+        operator: { id: null },
+      }),
+    ).toBe(true);
+    expect(() => gate.policy("public", () => true)).toThrow(/reserved/);
+    expect(() => gate.scope("public")).toThrow(/reserved/);
+  });
+
   test("defaults strategy to sliding-window-counter", () => {
     const r = gate.rate({ max: 10, per: "1s" });
     expect(r.strategy).toBe("sliding-window-counter");
@@ -117,7 +150,51 @@ describe("five rate strategies — concurrency", () => {
   });
 });
 
+describe("gate boot posture", () => {
+  const unguarded = [
+    {
+      trigger: { kind: "http" as const, method: "GET", path: "/health", gates: [] as const },
+      flow: { name: "health.ping" },
+    },
+  ];
+
+  test("GateBootError lists every unguarded HTTP trigger", () => {
+    expect(() =>
+      assertHttpGatePosture([
+        ...unguarded,
+        {
+          trigger: { kind: "http", method: "POST", path: "/x", gates: [gate.public] },
+          flow: { name: "x.public" },
+        },
+      ]),
+    ).toThrow(GateBootError);
+  });
+
+  test("unguardedHttp allow skips audit only when env is test", () => {
+    expect(() =>
+      assertHttpGatePosture(unguarded, { unguardedHttp: "allow", env: "test" }),
+    ).not.toThrow();
+  });
+
+  test("unguardedHttp allow has no effect outside env === test", () => {
+    for (const env of ["local", "prod", "docker"] as const) {
+      expect(() => assertHttpGatePosture(unguarded, { unguardedHttp: "allow", env })).toThrow(
+        GateBootError,
+      );
+    }
+  });
+});
+
 describe("gate runtime", () => {
+  test("public sentinel is always registered", async () => {
+    const rt = createGateRuntime();
+    const ok = await rt.allow(["public"], {
+      auth: { userId: null, scopes: new Set() },
+      operator: { id: null },
+    });
+    expect(ok).toBe(true);
+  });
+
   test("policy then rate — evaluation order", async () => {
     const kv = await memoryKvDriver.open({ name: "gate-rt" });
     const member = gate.policy("member", ({ auth }) => !!auth.verified);

package/src/elements/gate.ts

@@ -8,7 +8,7 @@
  * @module
  */
 
-export { gate } from "./gate/declare.ts";
+export { gate, GATE_PUBLIC_NAME } from "./gate/declare.ts";
 export type {
   GateDecl,
   GatePolicyContext,
@@ -18,6 +18,25 @@ export type {
   RateOptions,
 } from "./gate/declare.ts";
 
+export {
+  resolveGateConfig,
+  type GateOptions,
+  type GateRateLimitOptions,
+  type ResolvedGateConfig,
+  type ResolveGateConfigOptions,
+} from "./gate/config.ts";
+
+export {
+  GateBootError,
+  assertHttpGatePosture,
+  collectUnguardedHttpGaps,
+  hasHttpGatePosture,
+  isPublicGateRef,
+  unguardedHttpAllowActive,
+  type AssertHttpGatePostureOptions,
+  type GatePostureGap,
+} from "./gate/boot.ts";
+
 export {
   createGateRuntime,
   type CreateGateRuntimeOptions,

package/src/elements/index.ts

@@ -62,6 +62,13 @@ export type { ClockDecl, ClockOptions, ClockRuntime, TimeTravel, DurableResult }
 
 export {
   gate,
+  GATE_PUBLIC_NAME,
+  GateBootError,
+  assertHttpGatePosture,
+  collectUnguardedHttpGaps,
+  hasHttpGatePosture,
+  isPublicGateRef,
+  unguardedHttpAllowActive,
   createGateRuntime,
   takeRate,
   deriveModuleActions,
@@ -72,6 +79,7 @@ export {
 export type {
   GateDecl,
   GatePolicyContext,
+  GatePostureGap,
   GateRuntime,
   RateOptions,
   RateTakeResult,

package/src/index.ts

@@ -38,12 +38,16 @@ export {
   isRedacted,
   maskRedactedDeep,
   REDACTED_PLACEHOLDER,
+  PluginNeedsError,
+  assertPluginNeeds,
+  freezePrincipal,
   type OkeApp,
   type OkeOptions,
   type FlowDef,
   type FlowFailure,
   type FlowErrorValue,
   type Fx,
+  type FxPrincipal,
   type Binding,
   type PluginDef,
   type PluginCapabilities,
@@ -94,13 +98,20 @@ export {
 
 export {
   gate,
+  GATE_PUBLIC_NAME,
+  GateBootError,
+  assertHttpGatePosture,
   createGateRuntime,
+  resolveGateConfig,
   takeRate,
   deriveModuleActions,
   ALL_RATE_STRATEGIES,
   type GateDecl,
+  type GateOptions,
+  type GatePostureGap,
   type GateRuntime,
   type RateOptions,
+  type ResolvedGateConfig,
 } from "./elements/gate.ts";
 
 export {