@wildo-ai/platform-infra-providers 1.1.2

package/src/redis-self/redis-self.infra.module.ts

@@ -0,0 +1,372 @@
+/**
+ * `RedisSelfInfraProviderModule` — second concrete `InfraProviderModule`
+ * (Slice 4.B.1 of `infra-provider-planner.md`, generalizing the
+ * Slice 2 `RabbitmqSelfInfraProviderModule` pattern).
+ *
+ * Implements the `REDIS_SELF` `InfraProvider` over the
+ * `IRedisAclClient` transport (Valkey/Redis ACL commands, exposed by
+ * `RedisConnectionManagerService` after the Slice 4.B.1 5C policy/
+ * transport split). Owns ALL per-app ACL policy — the per-app
+ * keyPattern, the channel-pattern fan-out family, the per-app
+ * username convention.
+ *
+ * **What this module reads from `AppCredentialMintingContext`**:
+ * - `appSlug` — used as the **key-pattern** prefix
+ *   (`<appSlug>:*`). This MUST match the backend's effective
+ *   `dataServices.redis.keyPrefix`, which is the slug-derived key
+ *   namespace every backend write is rooted under (see
+ *   `engine/saas-backend-lib/src/databases/services/redis.service.ts`
+ *   `appPrefix` field — every `org:`/`global:` scope is composed with
+ *   that prefix). Slot owner: the SaaS app's authored config.
+ *   ACL invariant: `keyPrefix` MUST start with `<appSlug>:` so the
+ *   `~<appSlug>:*` grant covers every key the backend writes.
+ * - `applicationNamespace` — used as the Redis ACL **username** AND
+ *   as the channel-pattern prefix (`<ns>#*`, `<ns>-request#*`,
+ *   `<ns>-response#*`). Mirrors the legacy username convention from
+ *   `wildo-application-lifecycle.service.ts:441` (`redisUsername =
+ *   ns`). Channels stay namespace-scoped because the Socket.IO Redis
+ *   adapter (`engine/saas-backend-lib/src/requests/service/websocket
+ *   .service.ts:1501`) uses the Redis username as its `key:` — the
+ *   ACL channel pattern MUST match that.
+ * - `secretInputs['database.redis.password']` — orchestrator-supplied
+ *   password (module is upsert-only, never generator).
+ * - `adminClient` — narrowed to `IRedisAclClient`.
+ *
+ * **Key vs channel pattern split** (2026-05-26 framework-correct fix):
+ * Pre-fix, this module derived BOTH key and channel patterns from
+ * `applicationNamespace` (`<ns>:*` for keys, `<ns>#*` for channels).
+ * That was correct pre-Slice-3.6, when the backend used the username
+ * to namespace keys too. Slice 3.6 moved key namespacing to
+ * `dataServices.redis.keyPrefix` (default + recommended value
+ * `<appSlug>:`) but the ACL provisioner was not updated — every per-app
+ * Redis read/write returned `NOPERM No permissions to access a key`
+ * because the ACL only granted `<ns>:*` while the backend wrote
+ * `<appSlug>:*`. Fix: key pattern now derives from `appSlug`, channel
+ * patterns continue to derive from the username/namespace (Socket.IO
+ * adapter still uses the username as its channel key, so channels
+ * stay correct unchanged).
+ *
+ * **What this module IGNORES from the context** (Slice 4.A.2 / M4
+ * forward-compat documentation):
+ * - `wildoApplicationId` — the keyPattern uses appSlug + the channel
+ *   patterns use namespace; the application id is redundant for both
+ *   (no globally-shared key namespace risk because slug/namespace
+ *   already disambiguate by tenant and environment).
+ * - `applicationConfigInputs` — Redis_Self has no per-app authored
+ *   topology (no equivalent of RabbitMQ's vhost). Future modules may
+ *   read it for per-app db-index overrides etc.
+ *
+ * **Two audiences this module serves:**
+ *
+ * 1. **Audience-1 (platform-admin, declared via `plan().platformAdmin`)**:
+ *    cluster-wide ACL admin creds (`REDIS_HOST`, `REDIS_PORT`,
+ *    `REDIS_DATABASE` env + `REDIS_ADMIN_PASSWORD` secret env).
+ *    Consumers: `apps-manager` (mints per-app ACL users via
+ *    `mintAppCredentials`), `companion` (mirrors apps-manager admin
+ *    role for local dev).
+ *
+ * 2. **Audience-3 (app-scoped, via `plan().appRuntime` +
+ *    `mintAppCredentials`)**: per-customer-app Redis ACL user.
+ *    Username = `applicationNamespace`; keyPattern disambiguates by
+ *    the same namespace. Result threaded into
+ *    `Wildo_Application_Secrets.database.redis.{username, password}`
+ *    via `_merge_WildoApplicationSecrets`.
+ *
+ * **NOT served (D-4 of Slice 4.B locked decisions, 2026-05-10)**:
+ * - **Audience-2 (platform-service-scoped)**: Redis is currently NOT
+ *   used for inter-platform-service messaging (RabbitMQ is the bus).
+ *   `mintPlatformServiceCredentials` is therefore not implemented.
+ *   When/if a platform service surfaces a Redis-scoped per-service
+ *   credential need, this module gains the method.
+ *
+ * **`revokeAppCredentials`**: declared and tested, but the integration
+ * call site does NOT exist in `wildo-application-lifecycle.service.ts`
+ * (no app-deletion ceremony today — F6 of plan review 2026-05-06).
+ * Method ships as a forward-compat seam.
+ */
+
+import {
+  AppCredentialMintingContext,
+  AppCredentialMintingResult,
+  IRedisAclClient,
+  InfraCapability,
+  InfraPlatformAdminConsumer,
+  InfraProvider,
+  InfraProviderModule,
+  InfraProviderPlanContribution,
+  ApplicationRuntimePrincipalKind,
+  buildMinionRedisKeyPrefix,
+  type ApplicationRuntimePrincipal,
+} from '@wildo-ai/platform-config-lib';
+
+/**
+ * Default Valkey port (matches `INFRA_DEFAULT_PORTS.VALKEY` in the
+ * shared platform constants — duplicated here as a literal because
+ * the planner output is consumed by the CLI which materializes it
+ * into `Wildo_Application_Config` blob paths; the value is stable
+ * and small).
+ */
+const DEFAULT_VALKEY_PORT = 6379;
+
+/**
+ * Default DB index for app workloads. Wildo applications use db `0`
+ * across the board; per-app DB-index isolation is intentionally NOT
+ * modeled — keyPattern + ACL is the isolation seam.
+ */
+const DEFAULT_DB_INDEX = 0;
+
+/**
+ * The `Wildo_Application_Secrets` JSON paths this module writes
+ * through `mintAppCredentials`. Declared once and reused as
+ * `appRuntime.perAppSecretBlobPaths` in `plan()` AND as the keys of
+ * `secretBlobValues` in the result, so a refactor that renames a
+ * path fails loudly at one place instead of drifting silently.
+ */
+const REDIS_USERNAME_PATH = 'database.redis.username';
+const REDIS_PASSWORD_PATH = 'database.redis.password';
+/**
+ * The paths this module mints PER RUNTIME PRINCIPAL — the single source for both consumers.
+ *
+ * Read by `InfraProviderModule.perPrincipalSecretBlobPaths` (statically, so apps-manager can strip
+ * these from the application blob before delivering a principal's own material) AND spread into
+ * `appRuntime.perAppSecretBlobPaths` inside `plan()`. Declaring the list twice is how the delivery
+ * path would silently stop covering a path this module still mints.
+ */
+const PER_PRINCIPAL_SECRET_BLOB_PATHS: ReadonlyArray<string> = [REDIS_USERNAME_PATH, REDIS_PASSWORD_PATH];
+
+
+/**
+ * Compute the per-app Redis ACL username. Mirrors the existing
+ * convention at `wildo-application-lifecycle.service.ts:441`
+ * (`redisUsername = ns`) — username is the application namespace
+ * (`<appSlug>-<environmentId>`), NOT the raw slug. Centralized here
+ * so future changes touch one site.
+ */
+function buildRedisUsername(applicationNamespace: string): string {
+  return applicationNamespace;
+}
+
+/**
+ * Per-principal ACL username (Step 2 / D17).
+ *
+ * The application backend keeps `applicationNamespace` VERBATIM — its username
+ * must not move, or an existing deployment's ACL user is orphaned and a running
+ * backend loses Redis on the next sync.
+ *
+ * A named principal appends its kind and name. The separator is `-`: an ACL
+ * username is whitespace-delimited in `ACL SETUSER`, and the principal key's own
+ * `:` is already meaningful in Redis KEY space, so reusing it in a username
+ * blurs the two namespaces at a glance. Non-alphanumeric characters in a bucket
+ * key are collapsed — the key is a TypeScript object key and may legally contain
+ * `$` or `_`, while a username reaching the wire should stay conservative.
+ *
+ * Used by BOTH `mintAppCredentials` and `revokeAppCredentials`. That is the
+ * point of it being a function: a revoke that derived the username differently
+ * would delete the APPLICATION BACKEND's ACL user while believing it was
+ * removing a minion's.
+ */
+function buildRedisPrincipalUsername(
+  applicationNamespace: string,
+  principal: ApplicationRuntimePrincipal | undefined,
+): string {
+  if (!principal || principal.kind === ApplicationRuntimePrincipalKind.APPLICATION_BACKEND) {
+    return buildRedisUsername(applicationNamespace);
+  }
+  const sanitizedName = (principal.name ?? '').replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return `${applicationNamespace}-${principal.kind}-${sanitizedName}`;
+}
+
+/**
+ * Compute the per-app Redis ACL key pattern.
+ *
+ * The pattern derives from `appSlug` (NOT `applicationNamespace`)
+ * because the backend's effective key namespace is sourced from
+ * `dataServices.redis.keyPrefix` (Slice 3.6 — see
+ * `engine/saas-backend-lib/src/databases/services/redis.service.ts`
+ * `appPrefix` field JSDoc) whose default + recommended value is
+ * `<appSlug>:`. The ACL `~<appSlug>:*` rule must match the key shape
+ * the backend writes; ANY namespace-derived ACL (the pre-2026-05-26
+ * shape) would only grant `<ns>:*` and `NOPERM` every backend access.
+ *
+ * The channel patterns are computed separately from the username
+ * (== applicationNamespace) inside `IRedisAclClient.upsertUser`,
+ * because the Socket.IO Redis adapter uses the username as its
+ * channel key (`engine/saas-backend-lib/src/requests/service/
+ * websocket.service.ts:1501`). The two namespaces are split:
+ * - key namespace      = `<appSlug>:`  (app-authored
+ *                                       `dataServices.redis.keyPrefix`)
+ * - channel namespace  = `<applicationNamespace>#`  (Socket.IO adapter
+ *                                                    key, == redisUsername)
+ *
+ * App-author contract (validated by `validateKeyPrefixContract`
+ * downstream — see `databases.backend.schemas.ts`): if the SaaS app
+ * overrides the default `keyPrefix`, the override MUST still start
+ * with `<appSlug>:` so the `~<appSlug>:*` grant remains a superset
+ * of the keys the backend writes.
+ */
+function buildRedisKeyPattern(appSlug: string): string {
+  return `${appSlug}:*`;
+}
+
+export const RedisSelfInfraProviderModule: InfraProviderModule = {
+  provider: InfraProvider.REDIS_SELF,
+  supportedCapabilities: [InfraCapability.CACHE_MANAGER],
+  perPrincipalSecretBlobPaths: PER_PRINCIPAL_SECRET_BLOB_PATHS,
+
+  plan(): InfraProviderPlanContribution {
+    return {
+      dockerComposeServices: ['valkey'],
+      k8sResources: ['templates/infra/k8s/internal/valkey/deployment.yaml.hbs'],
+      platformAdmin: {
+        envVars: {
+          REDIS_HOST: 'valkey',
+          REDIS_PORT: String(DEFAULT_VALKEY_PORT),
+          REDIS_DATABASE: String(DEFAULT_DB_INDEX),
+        },
+        // ACL admin password is the only secret env. The legacy
+        // `RedisConnectionManagerService.initializeAclAdmin` reads it
+        // from `REDIS_ADMIN_PASSWORD`; the planner emits the key, the
+        // CLI's `env-vars-builder` writes the value at sync time.
+        secretEnvVars: ['REDIS_ADMIN_PASSWORD'],
+        // Audience-1 only (ACL-admin access). No audience-2
+        // platform-service-scoped Redis use case today (D-4).
+        consumers: [
+          InfraPlatformAdminConsumer.APPS_MANAGER,
+          InfraPlatformAdminConsumer.COMPANION,
+        ],
+      },
+      appRuntime: {
+        // Static topology — same for every app in this env.
+        // Per-app values (username/password) flow through
+        // `perAppSecretBlobPaths` below.
+        perAppConfigBlobPaths: {
+          'database.redis.host': 'valkey',
+          'database.redis.port': DEFAULT_VALKEY_PORT,
+          'database.redis.db': DEFAULT_DB_INDEX,
+        },
+        perAppSecretBlobPaths: [...PER_PRINCIPAL_SECRET_BLOB_PATHS],
+      },
+    };
+  },
+
+  async mintAppCredentials(
+    context: AppCredentialMintingContext,
+  ): Promise<AppCredentialMintingResult> {
+    const adminClient = context.adminClient as IRedisAclClient;
+    const password = context.secretInputs[REDIS_PASSWORD_PATH];
+    if (!password) {
+      throw new Error(
+        `RedisSelfInfraProviderModule.mintAppCredentials: ` +
+        `secretInputs is missing '${REDIS_PASSWORD_PATH}'. ` +
+        `The orchestrator MUST supply the Redis password — modules are upsert-only.`,
+      );
+    }
+    if (!context.applicationNamespace) {
+      throw new Error(
+        `RedisSelfInfraProviderModule.mintAppCredentials: ` +
+        `applicationNamespace is empty. ` +
+        `The orchestrator MUST supply a non-empty namespace.`,
+      );
+    }
+    if (!context.appSlug) {
+      throw new Error(
+        `RedisSelfInfraProviderModule.mintAppCredentials: ` +
+        `appSlug is empty. ` +
+        `The orchestrator MUST supply a non-empty appSlug — the ACL key ` +
+        `pattern derives from it (must match the backend's effective ` +
+        `\`dataServices.redis.keyPrefix\`, default \`<appSlug>:\`).`,
+      );
+    }
+
+    const username = buildRedisPrincipalUsername(context.applicationNamespace, context.principal);
+    // Key pattern derives from appSlug (matches backend `keyPrefix`),
+    // channel patterns derive from username/namespace inside upsertUser
+    // (matches Socket.IO adapter's `key:` config). See module JSDoc for
+    // the full key-vs-channel-namespace split rationale.
+    // A MINION is confined to its own namespace (D20); the application backend
+    // keeps the app-wide pattern.
+    //
+    // This and the minion's `REDIS_KEY_PREFIX` are ONE COUPLED PAIR — a
+    // mismatch DENIES every operation the minion performs, and the error names
+    // an ACL rather than the mismatch. Both sides derive from
+    // `buildMinionRedisKeyPrefix`, so they cannot drift.
+    const keyPattern = context.principal?.kind === ApplicationRuntimePrincipalKind.MINION && context.principal.name
+      ? `${buildMinionRedisKeyPrefix(context.appSlug, context.principal.name)}*`
+      : buildRedisKeyPattern(context.appSlug);
+
+    // ACL SETUSER — idempotent upsert. Replaces password + key
+    // patterns + channel patterns + category allow/deny on conflict.
+    //
+    // **Atomicity guard** (Slice 6 audit / F-2, 2026-05-10): the
+    // sequential `await upsertUser(); await persistAcl();` shape
+    // intentionally relies on JavaScript exception propagation —
+    // when `upsertUser` throws, the thrown error bubbles up the
+    // async stack BEFORE `persistAcl` is reached, leaving the ACL
+    // list on disk unchanged. The
+    // `redis-self.infra.module.test.ts` "atomicity guard" case pins
+    // this behavior. **DO NOT wrap this pair in a try/catch that
+    // swallows the upsert error** — that would silently persist a
+    // partially-applied state. Any future refactor that introduces
+    // a try-block here MUST re-throw on the upsert error AND must
+    // gate `persistAcl` on the upsert's success.
+    await adminClient.upsertUser({
+      username,
+      password,
+      keyPattern,
+    });
+
+    // Persist ACL list to disk so Valkey restarts don't lose tenant
+    // users. Mirrors the legacy
+    // `wildo-application-lifecycle.service.ts:540` pairing.
+    await adminClient.persistAcl();
+
+    return {
+      secretBlobValues: {
+        [REDIS_USERNAME_PATH]: username,
+        // Echo the orchestrator-supplied password — proves the module
+        // is upsert-only, not generator. The orchestrator persists
+        // this exact value into `Wildo_Application_Secrets`.
+        [REDIS_PASSWORD_PATH]: password,
+      },
+    };
+  },
+
+  /**
+   * Tear down the per-app Redis ACL user. Valkey ACL users are
+   * global (no vhost equivalent), so `deleteUser` removes the user
+   * (and its key/channel access) atomically.
+   *
+   * **Caller status** (F6 of 2026-05-06 plan review): no caller
+   * wires this in Slices 1–4.B.1.
+   * `wildo-application-lifecycle.service.ts` has no app-deletion
+   * ceremony to invoke it from. Method ships as a forward-compat
+   * seam for whichever future slice designs the app-deletion
+   * lifecycle.
+   *
+   * **Defensive validation** (Slice 4.A.2 / L4 pattern): empty
+   * `applicationNamespace` would call `ACL DELUSER` with an empty
+   * username (Valkey would either error or silently no-op,
+   * depending on version); we fail-loud instead so a bad caller
+   * surfaces immediately.
+   */
+  async revokeAppCredentials(context: AppCredentialMintingContext): Promise<void> {
+    if (!context.applicationNamespace) {
+      throw new Error(
+        `RedisSelfInfraProviderModule.revokeAppCredentials: ` +
+        `applicationNamespace is empty. ` +
+        `The orchestrator MUST supply a non-empty namespace.`,
+      );
+    }
+    const adminClient = context.adminClient as IRedisAclClient;
+    const username = buildRedisPrincipalUsername(context.applicationNamespace, context.principal);
+    await adminClient.deleteUser(username);
+    // Persist after deletion so the ACL list on disk stays in sync
+    // with the in-memory state. Mirrors mintAppCredentials' pairing.
+    await adminClient.persistAcl();
+  },
+
+  // No `mintPlatformServiceCredentials` (D-4 of Slice 4.B —
+  // audience-2 not applicable to Redis_Self today). When a real
+  // need surfaces, add the method here following the
+  // `RabbitmqSelfInfraProviderModule` shape.
+};