okengine 0.4.3 → 0.5.0

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 {