@strav/flag 0.3.32 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strav/flag",
-  "version": "0.3.32",
+  "version": "0.4.0",
   "type": "module",
   "description": "Feature flags for the Strav framework",
   "license": "MIT",
@@ -18,10 +18,10 @@
     "tsconfig.json"
   ],
   "peerDependencies": {
-    "@strav/kernel": "0.3.32",
-    "@strav/database": "0.3.32",
-    "@strav/http": "0.3.32",
-    "@strav/cli": "0.3.32"
+    "@strav/kernel": "0.4.0",
+    "@strav/database": "0.4.0",
+    "@strav/http": "0.4.0",
+    "@strav/cli": "0.4.0"
   },
   "scripts": {
     "test": "bun test tests/",

package/src/errors.ts

@@ -7,3 +7,19 @@ export class FeatureNotDefinedError extends FlagError {
     super(`Feature "${feature}" is not defined. Register it with flag.define().`)
   }
 }
+
+/**
+ * Thrown when `flag.strictScopes` is enabled and a flag operation is
+ * called without a scope (or with a null/undefined one). Catches the
+ * common bug where middleware forgets to pass `ctx.get('user')` and
+ * the lookup silently evaluates the global flag.
+ */
+export class MissingScopeError extends FlagError {
+  constructor(feature: string) {
+    super(
+      `Feature "${feature}" was evaluated without a scope, but flag.strictScopes is enabled. ` +
+        `Pass an explicit scope (e.g. flag.for(user).value('${feature}')) or call ` +
+        `flag.activateForEveryone('${feature}') for genuinely global flags.`
+    )
+  }
+}

package/src/flag_manager.ts

@@ -5,6 +5,7 @@ import type {
   DriverConfig,
   FeatureResolver,
   FeatureClassConstructor,
+  FlagActor,
   ScopeKey,
   Scopeable,
 } from './types.ts'
@@ -12,7 +13,7 @@ import { GLOBAL_SCOPE } from './types.ts'
 import type { FeatureStore } from './feature_store.ts'
 import { DatabaseDriver } from './drivers/database_driver.ts'
 import { ArrayDriver } from './drivers/array_driver.ts'
-import { FeatureNotDefinedError } from './errors.ts'
+import { FeatureNotDefinedError, MissingScopeError } from './errors.ts'
 import PendingScopedFeature from './pending_scope.ts'
 
 @inject
@@ -30,6 +31,7 @@ export default class FlagManager {
     FlagManager._config = {
       default: config.get('flag.default', 'database') as string,
       drivers: config.get('flag.drivers', {}) as Record<string, DriverConfig>,
+      strictScopes: config.get('flag.strictScopes', false) as boolean,
     }
   }
 
@@ -74,10 +76,31 @@ export default class FlagManager {
     return `${type}:${scope.id}`
   }
 
+  /**
+   * Resolve a scope to its key, applying the `strictScopes` policy on
+   * the READ path. A null/undefined scope under strict mode raises
+   * `MissingScopeError` so a forgotten request-context lookup doesn't
+   * silently return the global value.
+   *
+   * The WRITE path keeps the loose semantics — `activate(feature)`
+   * with no scope still writes to the global. Callers that want
+   * explicit-global writes should prefer `activateForEveryone()` /
+   * `deactivateForEveryone()`.
+   */
+  private static resolveScopeStrict(
+    feature: string,
+    scope: Scopeable | null | undefined
+  ): ScopeKey {
+    if (!scope && FlagManager._config?.strictScopes) {
+      throw new MissingScopeError(feature)
+    }
+    return FlagManager.serializeScope(scope)
+  }
+
   // ── Core resolution ────────────────────────────────────────────────
 
   static async value(feature: string, scope?: Scopeable | null): Promise<unknown> {
-    const scopeKey = FlagManager.serializeScope(scope)
+    const scopeKey = FlagManager.resolveScopeStrict(feature, scope)
     const cacheKey = FlagManager.cacheKey(feature, scopeKey)
 
     // 1. Check in-memory cache
@@ -131,34 +154,80 @@ export default class FlagManager {
 
   // ── Manual activation/deactivation ─────────────────────────────────
 
-  static async activate(feature: string, value?: unknown, scope?: Scopeable | null): Promise<void> {
+  /**
+   * Turn a flag on (or assign a rich value).
+   *
+   * Pass `actor` to record who made the change — the value is included
+   * in the `flag:updated` event payload so an audit hook can wire it
+   * through to `@strav/audit`. See the package CLAUDE.md for the
+   * recommended one-liner pattern.
+   */
+  static async activate(
+    feature: string,
+    value?: unknown,
+    scope?: Scopeable | null,
+    actor?: FlagActor | null
+  ): Promise<void> {
     const scopeKey = FlagManager.serializeScope(scope)
     const resolved = value !== undefined ? value : true
+    const previous = await FlagManager.store().get(feature, scopeKey)
     await FlagManager.store().set(feature, scopeKey, resolved)
     FlagManager._cache.set(FlagManager.cacheKey(feature, scopeKey), resolved)
-    await Emitter.emit('flag:updated', { feature, scope: scopeKey, value: resolved })
+    await Emitter.emit('flag:updated', {
+      feature,
+      scope: scopeKey,
+      value: resolved,
+      previous,
+      actor: actor ?? null,
+    })
   }
 
-  static async deactivate(feature: string, scope?: Scopeable | null): Promise<void> {
+  /**
+   * Turn a flag off.
+   *
+   * Pass `actor` to record who made the change — see {@link activate}.
+   */
+  static async deactivate(
+    feature: string,
+    scope?: Scopeable | null,
+    actor?: FlagActor | null
+  ): Promise<void> {
     const scopeKey = FlagManager.serializeScope(scope)
+    const previous = await FlagManager.store().get(feature, scopeKey)
     await FlagManager.store().set(feature, scopeKey, false)
     FlagManager._cache.set(FlagManager.cacheKey(feature, scopeKey), false)
-    await Emitter.emit('flag:updated', { feature, scope: scopeKey, value: false })
+    await Emitter.emit('flag:updated', {
+      feature,
+      scope: scopeKey,
+      value: false,
+      previous,
+      actor: actor ?? null,
+    })
   }
 
-  static async activateForEveryone(feature: string, value?: unknown): Promise<void> {
-    return FlagManager.activate(feature, value)
+  static async activateForEveryone(
+    feature: string,
+    value?: unknown,
+    actor?: FlagActor | null
+  ): Promise<void> {
+    return FlagManager.activate(feature, value, null, actor)
   }
 
-  static async deactivateForEveryone(feature: string): Promise<void> {
-    return FlagManager.deactivate(feature)
+  static async deactivateForEveryone(
+    feature: string,
+    actor?: FlagActor | null
+  ): Promise<void> {
+    return FlagManager.deactivate(feature, null, actor)
   }
 
   // ── Batch operations ───────────────────────────────────────────────
 
   static async values(features: string[], scope?: Scopeable | null): Promise<Map<string, unknown>> {
     const result = new Map<string, unknown>()
-    const scopeKey = FlagManager.serializeScope(scope)
+    // Use the first feature name in the strict-scope error message — every
+    // batch call shares the same scope so the missing-scope diagnosis is
+    // identical regardless of which feature trips the check.
+    const scopeKey = FlagManager.resolveScopeStrict(features[0] ?? '<batch>', scope)
 
     // Collect cache hits and misses
     const misses: string[] = []
@@ -231,7 +300,7 @@ export default class FlagManager {
   // ── Cleanup ────────────────────────────────────────────────────────
 
   static async forget(feature: string, scope?: Scopeable | null): Promise<void> {
-    const scopeKey = FlagManager.serializeScope(scope)
+    const scopeKey = FlagManager.resolveScopeStrict(feature, scope)
     await FlagManager.store().forget(feature, scopeKey)
     FlagManager._cache.delete(FlagManager.cacheKey(feature, scopeKey))
     await Emitter.emit('flag:deleted', { feature, scope: scopeKey })

package/src/index.ts

@@ -22,7 +22,7 @@ export { default as PendingScopedFeature } from './pending_scope.ts'
 export { ensureFeature } from './middleware/ensure_feature.ts'
 
 // Errors
-export { FlagError, FeatureNotDefinedError } from './errors.ts'
+export { FlagError, FeatureNotDefinedError, MissingScopeError } from './errors.ts'
 
 // Types
 export type {
@@ -34,5 +34,7 @@ export type {
   FeatureResolver,
   FeatureClass,
   FeatureClassConstructor,
+  FlagActor,
+  FlagUpdatedEvent,
 } from './types.ts'
 export { GLOBAL_SCOPE } from './types.ts'

package/src/pending_scope.ts

@@ -1,4 +1,4 @@
-import type { Scopeable } from './types.ts'
+import type { FlagActor, Scopeable } from './types.ts'
 import FlagManager from './flag_manager.ts'
 
 /** Fluent scoped feature check — created by `FlagManager.for(scope)`. */
@@ -25,12 +25,12 @@ export default class PendingScopedFeature {
     return FlagManager.when(feature, onActive, onInactive, this.scope)
   }
 
-  activate(feature: string, value?: unknown): Promise<void> {
-    return FlagManager.activate(feature, value, this.scope)
+  activate(feature: string, value?: unknown, actor?: FlagActor | null): Promise<void> {
+    return FlagManager.activate(feature, value, this.scope, actor)
   }
 
-  deactivate(feature: string): Promise<void> {
-    return FlagManager.deactivate(feature, this.scope)
+  deactivate(feature: string, actor?: FlagActor | null): Promise<void> {
+    return FlagManager.deactivate(feature, this.scope, actor)
   }
 
   forget(feature: string): Promise<void> {

package/src/types.ts

@@ -44,9 +44,48 @@ export interface StoredFeature {
 export interface FlagConfig {
   default: string
   drivers: Record<string, DriverConfig>
+  /**
+   * When true, calls to `value`/`active`/`activate`/`deactivate` that
+   * resolve to a null/undefined scope throw `MissingScopeError` instead
+   * of silently falling back to the global scope. Default: `false`
+   * (backwards-compatible). Apps that derive scope from request state
+   * (e.g., `ctx.get('user')`) should turn this on so a forgotten or
+   * unauthenticated request raises a loud error instead of evaluating
+   * the global flag for everyone.
+   */
+  strictScopes: boolean
 }
 
 export interface DriverConfig {
   driver: string
   [key: string]: unknown
 }
+
+// ── Actor ────────────────────────────────────────────────────────────────
+
+/**
+ * Who initiated a flag write. Optional, but recommended for accountability.
+ * Carried through to `flag:updated` event payloads so an audit hook can
+ * record the change. See `@strav/flag` CLAUDE.md for the recommended
+ * audit-integration pattern.
+ */
+export interface FlagActor {
+  type: string
+  id: string | number
+}
+
+// ── Events ───────────────────────────────────────────────────────────────
+
+/**
+ * Payload for the `flag:updated` Emitter event. Fired when `activate()`
+ * or `deactivate()` writes to the store.
+ */
+export interface FlagUpdatedEvent {
+  feature: string
+  scope: ScopeKey
+  value: unknown
+  /** Previous stored value (if any) — undefined when the flag had no prior store entry. */
+  previous: unknown
+  /** Who initiated the change. `null` when the caller did not provide an actor. */
+  actor: FlagActor | null
+}