@onlineapps/conn-orch-validator 10.0.0 → 11.0.0

package/src/manifest/checks/serviceRuntime.js

@@ -53,6 +53,9 @@ const SERVICE_MEMORY_PATH = 'deploy.resources.limits.memory';
 /** The profile that marks the test runner — its budget is F-RUNNER's row, not R-MEM's. */
 const TEST_PROFILE = 'test';
 
+/** How a compose service names the identity its container runs as. */
+const COMPOSE_USER_KEY = 'user';
+
 const readOrNull = (serviceRoot, relative) => {
   const target = path.join(serviceRoot, ...relative.split('/'));
   return fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
@@ -269,6 +272,125 @@ const composeCommand = Object.freeze({
   }
 });
 
+/**
+ * The instructions of ONE `FROM … AS <stage>` block, up to the next `FROM`.
+ *
+ * Comments are dropped, because the comment beside the identity names the very
+ * words this check reads and a comment is not an instruction.
+ *
+ * @param {string} dockerfile
+ * @param {string} stage the name after `AS`
+ * @returns {string[]|null} null when the file declares no such stage
+ */
+function stageInstructions(dockerfile, stage) {
+  const lines = dockerfile.split('\n').map((line) => line.trim());
+  const starts = lines
+    .map((line, index) => ({ line, index }))
+    .filter((entry) => /^FROM\s/i.test(entry.line));
+
+  const wanted = starts.find((entry) => new RegExp(`\\sAS\\s+${stage}\\s*$`, 'i').test(entry.line));
+  if (wanted === undefined) return null;
+
+  const after = starts.find((entry) => entry.index > wanted.index);
+  return lines
+    .slice(wanted.index, after === undefined ? lines.length : after.index)
+    .filter((line) => line !== '' && !line.startsWith('#'));
+}
+
+/**
+ * `R-USER` — WHICH USER the service process is.
+ *
+ * Measured 2026-09-17 on a production image built from the platform template:
+ * `docker run --rm <image> id` answered `uid=0(root) gid=0(root)`, while the dev
+ * container beside it ran as `1000:1000` because `docker-compose.yml` pins it.
+ * Nobody had decided that difference — the production stage declared no `USER`
+ * at all — and nothing in the uniform could say so, because `Dockerfile` is a
+ * file of the `own` class. This row is the SECOND platform fact carved out of
+ * that class, for the same reason as the first (`R-NODE`, the node major): what
+ * a service BUILDS is its own, what it RUNS AS is the platform's.
+ *
+ * Two facts, and they are the two nothing else holds:
+ *
+ *   * the `production` stage of the `Dockerfile` declares a non-root `USER` —
+ *     that is the stage CI builds (`docker build --target production`), and the
+ *     one the defect lived in;
+ *   * the SERVICE node of the dev compose pins the same identity numerically.
+ *
+ * The other two places it appears already have an owner, and a second rail over
+ * them would report one fact twice (`change-discipline.md` § One rail per
+ * concern): the runner's `user:` sits inside the block `F-RUNNER` holds byte for
+ * byte, and the production compose is `G-PROD`'s whole-file render.
+ *
+ * The two spellings are one identity, and the row carries both because no
+ * machine can resolve an account NAME to a uid without the image: `node` is uid
+ * 1000, gid 1000 in the node images this platform builds on (measured
+ * `docker run --rm node:24-alpine id node`), which is the `1000:1000` the compose
+ * files pin. Same shape as `R-MEM` and `R-PID1`, which carry their values for
+ * the same reason.
+ *
+ * @see api/docs/biz/00-model/service-shape.md
+ */
+const processIdentity = Object.freeze({
+  scope: 'service',
+  requires: Object.freeze(['path', 'image_path', 'image_stage', 'service_user', 'service_uid']),
+
+  run({ row, serviceRoot, workspaceRoot }) {
+    const findings = [];
+    const identity = `the platform identity is ${JSON.stringify(row.service_user)} `
+      + '(uid 1000, gid 1000 in the node images this platform builds on)';
+    const imageWhere = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.image_path });
+
+    const dockerfile = readOrNull(serviceRoot, row.image_path);
+    if (dockerfile === null) {
+      findings.push({ where: imageWhere, what: 'absent — the image this service runs as is built from it' });
+    } else {
+      const stage = stageInstructions(dockerfile, row.image_stage);
+      if (stage === null) {
+        findings.push({
+          where: imageWhere,
+          what: `declares no stage "AS ${row.image_stage}" — that is the stage CI builds, so nothing here `
+            + 'says what the deployed container runs as'
+        });
+      } else {
+        // The LAST one wins, the way docker reads it: a stage may switch twice,
+        // and what the container runs as is whatever stood at the end.
+        const declared = stage.filter((line) => /^USER\s/i.test(line)).pop();
+        if (declared === undefined) {
+          findings.push({
+            where: imageWhere,
+            what: `the ${row.image_stage} stage declares no USER, so the container runs as root — ${identity}`
+          });
+        } else if (declared.replace(/^USER\s+/i, '').trim() !== row.service_user) {
+          findings.push({
+            where: imageWhere,
+            what: `the ${row.image_stage} stage runs as ${JSON.stringify(declared.replace(/^USER\s+/i, '').trim())} — ${identity}`
+          });
+        }
+      }
+    }
+
+    const composeWhere = whereOf({ scope: 'bearer', serviceRoot, workspaceRoot, relative: row.path });
+    const compose = readOrNull(serviceRoot, row.path);
+    if (compose === null) {
+      findings.push({ where: composeWhere, what: 'absent — the service is run from it' });
+      return findings;
+    }
+
+    for (const [name, node] of runtimeServices(compose)) {
+      const declared = declarationOf(node, COMPOSE_USER_KEY).trim().replace(/^["']|["']$/g, '');
+      if (declared === row.service_uid) continue;
+      findings.push({
+        where: composeWhere,
+        what: declared === ''
+          ? `service ${name} declares no user — the platform identity is ${JSON.stringify(row.service_uid)}`
+          : `service ${name} runs as ${JSON.stringify(declared)} — the platform identity is ${JSON.stringify(row.service_uid)}`
+      });
+    }
+
+    return findings;
+  }
+});
+
 const composeNoPorts = Object.freeze({
   scope: 'service',
   requires: Object.freeze(['path']),
@@ -291,6 +413,7 @@ module.exports = {
     { name: 'node-major', check: nodeMajor },
     { name: 'memory-limit', check: memoryLimit },
     { name: 'compose-command', check: composeCommand },
+    { name: 'process-identity', check: processIdentity },
     { name: 'compose-no-ports', check: composeNoPorts }
   ],
   majorOf

package/src/manifest/gitCheckout.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * The one probe that answers "is this tree a git checkout" — and the one command
+ * that asks it.
+ *
+ * Two places need the answer and they must never disagree:
+ *
+ *   - the `git-tracked` row (`checks/gitTracked.js`), which asks what a clone
+ *     would receive and reports NOT RUN where git cannot say;
+ *   - step 7 of `ValidationOrchestrator`, which measures the whole uniform and,
+ *     outside a checkout, is NOT RUN for the same reason (owner decision
+ *     2026-09-17, confirmation `api/docs/governance/confirmations/biz-service-manifest.md`
+ *     011).
+ *
+ * A second copy of `git ls-files` would be a second rail for one concern
+ * (`.claude/rules/change-discipline.md` § One rail per concern) and, worse, two
+ * rails that can answer differently: one of them would eventually grow a
+ * `.git` existence check, which is not the same question — a worktree, a
+ * submodule and a `$GIT_DIR` elsewhere are checkouts without a `.git`
+ * DIRECTORY, and a directory called `.git` inside an exported tarball is not a
+ * checkout. What decides is whether git itself can answer.
+ *
+ * Nothing here guesses: a command git could not answer returns `null`, and the
+ * caller turns that into NOT RUN. What a negative answer MEANS is stated here
+ * once, in `NOT_A_CHECKOUT`; the remedy is the caller's own, because a row and a
+ * whole step do not fix the same way.
+ */
+
+const { execFileSync } = require('child_process');
+
+/**
+ * What a negative answer means — the half both callers state identically, so it
+ * cannot drift into two versions of one fact. Each of them appends its own
+ * remedy sentence after it.
+ */
+const NOT_A_CHECKOUT = 'this tree is not a git checkout (git ls-files could not answer), so what a clone '
+  + 'would receive cannot be read — a container and an exported tarball are in exactly this state.';
+
+/**
+ * Run one git command in the tree, or return null when git itself could not
+ * answer.
+ *
+ * @param {string} root the directory to run in
+ * @param {string[]} args the git arguments, without `-C <root>`
+ * @param {string} [input] stdin for commands that read it
+ * @returns {string|null} stdout, or null when git could not answer
+ */
+function gitCommand(root, args, input = undefined) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      input,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+  } catch (error) {
+    // check-ignore exits 1 when nothing matched, which is an ANSWER.
+    if (error.status === 1 && typeof error.stdout === 'string') return error.stdout;
+    return null;
+  }
+}
+
+/**
+ * What git tracks in this tree, NUL-separated exactly as `git ls-files -z`
+ * printed it — or null when this is not a checkout.
+ *
+ * @param {string} root
+ * @returns {string|null}
+ */
+function listTrackedFiles(root) {
+  return gitCommand(root, ['ls-files', '-z']);
+}
+
+/**
+ * Is this tree a git checkout?
+ *
+ * @param {string} root
+ * @returns {boolean}
+ */
+function isGitCheckout(root) {
+  return listTrackedFiles(root) !== null;
+}
+
+module.exports = { gitCommand, listTrackedFiles, isGitCheckout, NOT_A_CHECKOUT };

package/src/utils/dbAccountGrants.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * The one definition of a biz service's database account.
+ *
+ * Owner decision `db-accounts-per-service` 001: every service reaches its schema
+ * as ITSELF, with grants on its own schemas, and root stops being an operational
+ * identity. `db-migrations-first-deploy` 001 says what that is worth — "migrace
+ * nikdy pod rootem" (:32) — and, in the same breath, "žádný nový generátor SQL …
+ * žádná druhá kolej" (:33). So these statements exist ONCE: the production
+ * runbook (`api/docs/setup/INSTALL.md` § the account and its grants) and
+ * `biz-ci-gate setup-db-account` are two CALLERS of this function, not two
+ * copies of the same SQL.
+ *
+ * `createDatabaseSql` in `setupDatabase.js` stays where it is and is not
+ * re-exported here: creating the SCHEMA and creating the ACCOUNT are two
+ * concerns with two moments (the account exists before the schema in CI, and is
+ * created by the operator before the installer runs in production).
+ *
+ * ## The one difference between CI and production
+ *
+ * An integration suite builds THROWAWAY schemas beside the declared one —
+ * `src/utils/throwawaySchema.js`, used today as `oagen_emailer_fixture_<ms>_<pid>`
+ * (`api_biz/emailer/tests/integration/fixtureSchema.js`) and
+ * `oagen_meta_platformseedtest` (`api_biz/meta`). A grant on `oagen_emailer`
+ * alone refuses every one of them, which is why `ciThrowaway: true` adds a
+ * second grant over the service's own namespace.
+ *
+ * It does NOT widen the account's reach to another service: the pattern is
+ * anchored on this schema's name, and the `_` is ESCAPED. Unescaped, `_` is a
+ * single-character LIKE wildcard, so `oagen_meta_%` would also match
+ * `oagen_metadata` — a neighbouring service handed over whole. The backslash is
+ * what keeps the grant inside one service, and it is the difference
+ * `tests/unit/dbAccountGrants.test.js` measures.
+ *
+ * Production never gets that grant: it installs one schema, and a wildcard there
+ * would be a standing privilege nobody asked for.
+ *
+ * ## What is deliberately NOT here
+ *
+ * `GRANT SELECT ON information_schema.*` — the privilege
+ * `setupDatabase.assertTargetIsEmpty` names in its own error message. The server
+ * refuses to grant it at all (measured 2026-09-16, dev `gen_mariadb10.5`,
+ * MariaDB 10.5.17: `ERROR 1044 (42000): Access denied for user 'root'@'localhost'
+ * to database 'information_schema'`). Every account reads that catalogue
+ * already, filtered to the schemas it is granted — which is precisely the answer
+ * the emptiness probe needs.
+ *
+ * @see api/docs/governance/confirmations/db-accounts-per-service.md
+ * @see api/docs/governance/confirmations/db-migrations-first-deploy.md
+ * @see src/utils/setupDatabase.js
+ */
+
+/**
+ * The host part of every account. One value, because a second spelling is a
+ * second account: `'x'@'%'` and `'x'@'localhost'` are different rows in
+ * `mysql.user`, with different grants, and an installer that picked one while
+ * the gate created the other would report an account the service cannot use.
+ */
+const ACCOUNT_HOST = '%';
+
+/**
+ * Identifiers and passwords reach the server as TEXT, so they are checked rather
+ * than escaped: an identifier in this platform is `oagen_<shortname>`, and
+ * anything carrying a quote, a backslash or a backtick is not one.
+ *
+ * Refusing is the whole of the answer (`architecture-principles.md` §3): a value
+ * that needs escaping here came from somewhere it should not have.
+ */
+const FORBIDDEN_IN_VALUE = /['"`\\;\n\r]/;
+
+function requireValue(value, name, fix) {
+  if (typeof value !== 'string' || value === '') {
+    throw new Error(`[DbAccountGrants] Missing ${name} - Expected a non-empty value.\n`
+      + `       Fix: ${fix}`);
+  }
+  if (FORBIDDEN_IN_VALUE.test(value)) {
+    throw new Error(`[DbAccountGrants] ${name} carries a character these statements cannot contain: `
+      + `${JSON.stringify(value)}.\n`
+      + '       The statements are text handed to the SQL client, so a quote, backslash, backtick, '
+      + 'semicolon or newline would end one statement and start another.\n'
+      + `       Fix: ${fix}`);
+  }
+  return value;
+}
+
+/**
+ * Every statement that creates this service's account and grants it what it
+ * needs, in the order they must run.
+ *
+ * @param {object} options
+ * @param {string} options.schema the schema the service declares
+ *   (`database.schema` of `config/service/integration-contract.json`)
+ * @param {string} options.account the account the service declares
+ *   (`DB_USER` of `config/env-templates/<service>.env`)
+ * @param {string} options.password the password the account is created with
+ * @param {boolean} [options.ciThrowaway] also grant the throwaway namespace
+ *   `<schema>\_%`, which only an integration tier builds into
+ * @returns {string[]} the statements, in order
+ */
+function databaseAccountSql({ schema, account, password, ciThrowaway = false } = {}) {
+  requireValue(schema, 'schema', 'pass database.schema from config/service/integration-contract.json.');
+  requireValue(account, 'account', 'pass DB_USER from this service\'s config/env-templates/<service>.env.');
+  requireValue(password, 'password', 'pass the password the account is created with; an account created '
+    + 'with an empty password is one anybody on the network can use.');
+
+  const identity = `'${account}'@'${ACCOUNT_HOST}'`;
+
+  const statements = [
+    `CREATE USER IF NOT EXISTS ${identity} IDENTIFIED BY '${password}';`,
+    `GRANT ALL PRIVILEGES ON \`${schema}\`.* TO ${identity};`
+  ];
+
+  if (ciThrowaway === true) {
+    // The backslash escapes `_` so the pattern stays inside this service; see
+    // the head of this file for the neighbour it would otherwise reach.
+    statements.push(`GRANT ALL PRIVILEGES ON \`${schema}\\_%\`.* TO ${identity};`);
+  }
+
+  // Last, always: a grant is not live for a connection opened before it.
+  statements.push('FLUSH PRIVILEGES;');
+
+  return statements;
+}
+
+module.exports = { databaseAccountSql, ACCOUNT_HOST };

package/src/utils/envContract.js

@@ -378,17 +378,26 @@ function assertScannableServiceRoot(serviceRoot) {
 }
 
 /**
- * COMPLETENESS: every environment name the repository visibly reads is either
- * declared in the env block or covered by M1/M2.
+ * The names this service's environment is ALLOWED to be judged by: everything
+ * the declaration names, plus everything M1/M2 already cover.
+ *
+ * It is the set `verifyEnvCompleteness` measures the repository against, lifted
+ * out of it so a second caller cannot grow a second definition of it (d.533c;
+ * `change-discipline.md` § One rail per concern). The completeness check below
+ * asks the same question from the other side — which read is NOT in this set —
+ * and `oa-validate --env-reads` prints the set itself, for the deploy gate that
+ * must not demand a value for a name this service never reads.
+ *
+ * Sorted with the default comparator rather than `localeCompare`: the order is
+ * read by a machine, and a collation that depends on the host's locale data is
+ * the ambient state `automation-gates.md` §1.1 forbids.
  *
  * @param {object} args
  * @param {string} args.serviceRoot
  * @param {object} args.contract normalized integration contract
- * @returns {{ok: boolean, violations: Array<{name: string, sources: string[]}>, declaredCount: number,
- *            coveredCount: number, readCount: number, filesScanned: number,
- *            dynamicSites: Array<{file: string, line: number}>}}
+ * @returns {{names: string[], coverage: Map<string,string>, declared: Set<string>}}
  */
-function verifyEnvCompleteness({ serviceRoot, contract }) {
+function collectDeclaredEnvNames({ serviceRoot, contract }) {
   assertScannableServiceRoot(serviceRoot);
   assertNormalizedContract(contract);
 
@@ -409,6 +418,26 @@ function verifyEnvCompleteness({ serviceRoot, contract }) {
     for (const item of declaration?.[listKey] ?? []) declared.add(item.name);
   }
 
+  const names = new Set(coverage.keys());
+  for (const name of declared) names.add(name);
+
+  return { names: [...names].sort(), coverage, declared };
+}
+
+/**
+ * COMPLETENESS: every environment name the repository visibly reads is either
+ * declared in the env block or covered by M1/M2.
+ *
+ * @param {object} args
+ * @param {string} args.serviceRoot
+ * @param {object} args.contract normalized integration contract
+ * @returns {{ok: boolean, violations: Array<{name: string, sources: string[]}>, declaredCount: number,
+ *            coveredCount: number, readCount: number, filesScanned: number,
+ *            dynamicSites: Array<{file: string, line: number}>}}
+ */
+function verifyEnvCompleteness({ serviceRoot, contract }) {
+  const { coverage, declared } = collectDeclaredEnvNames({ serviceRoot, contract });
+
   const { reads, dynamicSites, filesScanned } = collectEnvReads({ serviceRoot });
 
   const violations = [];
@@ -467,6 +496,7 @@ module.exports = {
   ENV_SCAN_BLIND_SPOTS,
   normalizeEnvDeclaration,
   collectEnvCoverage,
+  collectDeclaredEnvNames,
   collectEnvReads,
   verifyEnvCompleteness,
   verifyEnvPresence

package/src/utils/envReads.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * Which environment names a service's image reads — asked by a deploy gate,
+ * answered by the contract (d.533c).
+ *
+ * ## The defect this ends
+ *
+ * `api/scripts/validate-env.sh` refuses a deploy when a key in the target's
+ * `.env` still says `CHANGE_ME`. Pointed at a biz service it refused on
+ * `JWT_SECRET`, a key the gateway reads and no biz image ever opens: the gate
+ * was judging the platform's whole key set against one service. The fix is not
+ * a list of exceptions in bash — it is the service saying what it reads.
+ *
+ * ## Why not a grep for `process.env`
+ *
+ * Because most of the platform's environment is read inside installed
+ * libraries: `@onlineapps/service-wrapper` reads `SECRETS_MASTER_KEYS`,
+ * `@onlineapps/conn-base-cache` reads `REDIS_URL`. A grep over `src/` sees none
+ * of them and would answer a set too small — which in a gate means a key
+ * silently unchecked. That blind spot is stated, not discovered:
+ * `utils/envContract.js` § Measurability boundary.
+ *
+ * ## The set is the uniform's, not a second definition
+ *
+ * The answer is `collectDeclaredEnvNames` — the contract's `env` block, the
+ * `${VAR}` placeholders of `config/service/*.json`, and the endpoint variables
+ * of the connectors the contract declares required. That is exactly the set row
+ * `C-ENV-READS` of the biz-service uniform measures the repository against, so
+ * the two can never disagree about what a service reads
+ * (`change-discipline.md` § One rail per concern).
+ *
+ * The consequence is deliberate: a name the SOURCE reads and the contract does
+ * not declare is absent from this answer. It is a blocking finding of
+ * `C-ENV-READS`, with its own fix, and a gate must not demand a value for a key
+ * nobody owns.
+ *
+ * The messages carry the context `[oa-validate]` because the subcommand is this
+ * module's only caller and the message goes to a bash gate reading stderr; there
+ * is no wrapper re-wording them, which is how they stay the exact sentence the
+ * test asserts (`automation-gates.md` §2).
+ *
+ * @see api/docs/biz/70-contracts/env-contract.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadAndValidateIntegrationContract } = require('./bizCiGateContract');
+const { collectDeclaredEnvNames } = require('./envContract');
+
+/** Where every biz service declares what it integrates with. */
+const CONTRACT_RELATIVE_PATH = path.join('config', 'service', 'integration-contract.json');
+
+/**
+ * Every environment name the service at `serviceRoot` reads, as the uniform
+ * measures it.
+ *
+ * @param {string} serviceRoot repository root of the service; the caller
+ *   resolves its own default, so an empty value is refused rather than silently
+ *   answered about `process.cwd()`
+ * @returns {string[]} the names, sorted, without duplicates
+ * @throws {Error} when the root or the contract cannot be read — a gate that
+ *   cannot get the set must stop, never continue with an empty one
+ */
+function listEnvReads(serviceRoot) {
+  if (typeof serviceRoot !== 'string' || serviceRoot.trim() === '') {
+    throw new Error('[oa-validate] No service root to answer about - --env-reads was given '
+      + `${typeof serviceRoot === 'string' ? 'an empty path' : typeof serviceRoot}. `
+      + 'Fix: oa-validate --env-reads <serviceRoot>, or run it inside the service repository.');
+  }
+
+  const root = path.resolve(serviceRoot);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`[oa-validate] Service root not found - ${root}. `
+      + 'Fix: pass an existing repository directory, or run the command inside the service repository.');
+  }
+
+  const contractPath = path.join(root, CONTRACT_RELATIVE_PATH);
+  if (!fs.existsSync(contractPath)) {
+    throw new Error(`[oa-validate] No environment contract - ${contractPath} does not exist, so nothing `
+      + 'declares which environment names this service reads and the answer would be an empty set. '
+      + 'Fix: add config/service/integration-contract.json with requiredConnectors and, where the '
+      + 'service reads a name no placeholder and no connector covers, an "env" block.');
+  }
+
+  let contract;
+  try {
+    contract = loadAndValidateIntegrationContract(root).contract;
+  } catch (error) {
+    throw new Error(`[oa-validate] Unusable environment contract - ${contractPath}: `
+      + `${String(error.message).split('\n')[0].trim()} `
+      + 'Fix: correct the contract, then run npx oa-validate to see the row that judges it.');
+  }
+
+  return collectDeclaredEnvNames({ serviceRoot: root, contract }).names;
+}
+
+module.exports = {
+  CONTRACT_RELATIVE_PATH,
+  listEnvReads
+};