@oondemand/oon-core-back 0.6.8 → 0.6.10

package/bin/delivery.js

@@ -5,6 +5,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { getContextWithPhase, setState, addEvidence } = require("../src/delivery/api");
 const { provisionRuntime, deployRuntime, waitHttp, activateMember } = require("../src/delivery/runtime");
+const { canonicalizeDeliveryContext } = require("../src/delivery/technicalIdentity");
 
 function flag(name, fallback) {
   const args = process.argv.slice(3);
@@ -16,6 +17,7 @@ function flag(name, fallback) {
 }
 function required(value, name) { if (!value) throw new Error(`${name} obrigatório.`); return value; }
 function secret() { return required(process.env.OON_DELIVERY_SHARED_SECRET, "OON_DELIVERY_SHARED_SECRET"); }
+function normalizedContext(value) { return { ...canonicalizeDeliveryContext(value) }; }
 
 async function main() {
   const command = process.argv[2];
@@ -25,7 +27,8 @@ async function main() {
   if (command === "context") {
     const phase = flag("--phase", "build");
     const output = required(flag("--output"), "--output");
-    const context = await getContextWithPhase({ apiUrl: required(apiUrl, "--api"), releaseId: required(releaseId, "--release"), token: secret(), phase });
+    const fetched = await getContextWithPhase({ apiUrl: required(apiUrl, "--api"), releaseId: required(releaseId, "--release"), token: secret(), phase });
+    const context = normalizedContext(fetched);
     fs.writeFileSync(path.resolve(output), JSON.stringify(context, null, 2), { mode: 0o600 });
     return;
   }
@@ -40,7 +43,7 @@ async function main() {
   if (command === "deploy") {
     const contextFile = required(flag("--context"), "--context");
     const imageDigest = required(flag("--image-digest"), "--image-digest");
-    const context = JSON.parse(fs.readFileSync(path.resolve(contextFile), "utf8"));
+    const context = normalizedContext(JSON.parse(fs.readFileSync(path.resolve(contextFile), "utf8")));
     let failureState = "falha_infra";
     try {
       await setState({ apiUrl, releaseId, token: secret(), etapa: "provisionando", imageDigest });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/oon-core-back",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",

package/src/core/technicalIdentity.js

@@ -113,6 +113,10 @@ function technicalIdentity({ appCode, instanceUid, environment }) {
   const mongoUsername = `${base}-rw`;
   const serviceAccount = `${base}-runtime`;
   const secret = `${base}-runtime`;
+  const provisionJob = `${base}-provision`;
+  const frontendDnsLabel = base;
+  const backendDnsLabel = `${base}-api`;
+  const tlsSecret = `${base}-tls`;
 
   const lengths = {
     base: base.length,
@@ -120,6 +124,10 @@ function technicalIdentity({ appCode, instanceUid, environment }) {
     mongoUsername: mongoUsername.length,
     serviceAccount: serviceAccount.length,
     secret: secret.length,
+    provisionJob: provisionJob.length,
+    frontendDnsLabel: frontendDnsLabel.length,
+    backendDnsLabel: backendDnsLabel.length,
+    tlsSecret: tlsSecret.length,
   };
   const invalidLength = Object.entries(lengths).find(([, length]) => length > 63);
   if (invalidLength) {
@@ -141,6 +149,10 @@ function technicalIdentity({ appCode, instanceUid, environment }) {
     mongoUsername,
     serviceAccount,
     secret,
+    provisionJob,
+    frontendDnsLabel,
+    backendDnsLabel,
+    tlsSecret,
   });
 }
 
@@ -159,4 +171,4 @@ module.exports = Object.freeze({
   encodeInstanceUid,
   generateInstanceUid,
   technicalIdentity,
-});
+});

package/src/delivery/mongoCredentialLifecycle.js

@@ -0,0 +1,33 @@
+"use strict";
+
+const { assertMongoIdentity, recoveryRequired } = require("./mongoProvisioning");
+
+// The store must create the intent exclusively, then replace it by resourceVersion.
+// A present record without a credential is an interrupted operation, never absence.
+async function resolveMongoCredential({ identity, read, begin, persist, provision, validate }) {
+  const record = await read();
+  if (record !== null) {
+    if (!record.mongoUri) throw recoveryRequired("MONGO_CREDENTIAL_MISSING");
+    assertMongoIdentity(record.mongoUri, identity);
+    try { await validate(record.mongoUri); }
+    catch { throw recoveryRequired("MONGO_PERSISTED_CREDENTIAL_INVALID"); }
+    return { mongoUri: record.mongoUri, created: false };
+  }
+
+  await begin();
+  let captured;
+  try {
+    const result = await provision(async (uri) => {
+      assertMongoIdentity(uri, identity);
+      await persist(uri);
+      captured = uri;
+    });
+    if (!captured || result.mongoUri !== captured) throw recoveryRequired();
+    return { mongoUri: captured, created: true };
+  } catch {
+    // Do not serialize driver/provider errors, URIs, tokens or creation responses.
+    throw recoveryRequired("MONGO_PROVISIONING_INCOMPLETE");
+  }
+}
+
+module.exports = { resolveMongoCredential };

package/src/delivery/mongoProvisioning.js

@@ -1,11 +1,11 @@
 "use strict";
 
-const { mongo } = require("mongoose");
+const defaultMongoClient = () => require("mongoose").mongo.MongoClient;
+const { technicalIdentity } = require("../core/technicalIdentity");
 
 const DIGITALOCEAN_API = "https://api.digitalocean.com/v2";
 const DIGITALOCEAN_HOST_SUFFIX = ".mongo.ondigitalocean.com";
 const DIGITALOCEAN_RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
-const DIGITALOCEAN_SERVER_STATUS = new Set([500, 502, 503, 504]);
 
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -24,53 +24,76 @@ function dnsLabel(value, max = 63) {
     .replace(/-+$/, "");
 }
 
-function mongoIdentity(appCode, environment) {
+function mongoIdentity(appCode, environment, { instanceUid } = {}) {
+  if (instanceUid != null) {
+    const identity = technicalIdentity({ appCode, instanceUid, environment });
+    return {
+      mode: "canonical",
+      identityVersion: identity.version,
+      instanceUid: identity.instanceUid,
+      dbName: identity.database,
+      username: identity.mongoUsername,
+    };
+  }
   return {
+    mode: "legacy",
     dbName: dnsLabel(`${appCode}_${environment}`, 48).replace(/-/g, "_"),
     username: dnsLabel(`${appCode}-${environment}`, 48),
   };
 }
 
-function mongoHost(uri) {
+function recoveryRequired(code = "MONGO_RECOVERY_REQUIRED") {
+  const error = new Error(`${code}: recuperação explícita necessária; credenciais preservadas.`);
+  error.code = code;
+  return error;
+}
+
+// WHATWG URL rejects MongoDB seed lists with multiple host:port pairs.
+function parseMongoUri(uri) {
+  const match = typeof uri === "string" && uri.match(/^(mongodb(?:\+srv)?):\/\/([^/?#]+)(?:\/([^?#]*))?(?:\?([^#]*))?$/);
+  if (!match) throw recoveryRequired("MONGO_URI_INVALID");
+  const [, scheme, authority, database = "", query = ""] = match;
+  const at = authority.lastIndexOf("@");
+  const credentials = at < 0 ? "" : authority.slice(0, at);
+  const hosts = authority.slice(at + 1);
+  if (!hosts) throw recoveryRequired("MONGO_URI_INVALID");
   try {
-    return new URL(uri).hostname.toLowerCase();
-  } catch {
-    throw new Error("MONGO_ADMIN_URI inválida.");
-  }
+    return { scheme, hosts, database: decodeURIComponent(database),
+      username: decodeURIComponent(credentials.split(":")[0]), query: new URLSearchParams(query) };
+  } catch { throw recoveryRequired("MONGO_URI_INVALID"); }
+}
+
+function mongoHost(uri) {
+  const parsed = parseMongoUri(uri);
+  return parsed.hosts.split(",")[0].replace(/:\d+$/, "").toLowerCase();
 }
 
 function resolveMongoProvisioner({ adminUri, provisioner = "auto" }) {
   const normalized = String(provisioner || "auto").trim().toLowerCase();
   if (!["auto", "native", "digitalocean"].includes(normalized)) {
-    throw new Error(
-      `MONGO_PROVISIONER inválido: ${normalized}. Use auto, native ou digitalocean.`,
-    );
+    throw recoveryRequired("MONGO_PROVISIONER_INVALID");
   }
   if (normalized !== "auto") return normalized;
-  return mongoHost(adminUri).endsWith(DIGITALOCEAN_HOST_SUFFIX)
-    ? "digitalocean"
-    : "native";
+  return mongoHost(adminUri).endsWith(DIGITALOCEAN_HOST_SUFFIX) ? "digitalocean" : "native";
 }
 
-function buildRuntimeMongoUri({
-  adminUri,
-  username,
-  password,
-  dbName,
-  authSource,
-}) {
-  const uri = new URL(adminUri);
-  uri.username = username;
-  uri.password = password;
-  uri.pathname = `/${dbName}`;
-  uri.searchParams.set("authSource", authSource);
-  return uri.toString();
+function buildRuntimeMongoUri({ adminUri, username, password, dbName, authSource }) {
+  const parsed = parseMongoUri(adminUri);
+  parsed.query.set("authSource", authSource);
+  return `${parsed.scheme}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${parsed.hosts}/${encodeURIComponent(dbName)}?${parsed.query}`;
+}
+
+function assertMongoIdentity(uri, identity) {
+  const parsed = parseMongoUri(uri);
+  if (parsed.username !== identity.username || parsed.database !== identity.dbName) {
+    throw recoveryRequired("MONGO_IDENTITY_MISMATCH");
+  }
 }
 
 async function validateMongoUri(
   mongoUri,
   {
-    MongoClient = mongo.MongoClient,
+    MongoClient = defaultMongoClient(),
     timeoutMs = 15000,
     writeProbe = true,
   } = {},
@@ -81,9 +104,16 @@ async function validateMongoUri(
     maxPoolSize: 2,
   });
 
-  await client.connect();
   try {
+    await client.connect();
     const db = client.db();
+    const target = parseMongoUri(mongoUri);
+    const status = await db.command({ connectionStatus: 1 });
+    const roles = status?.authInfo?.authenticatedUserRoles;
+    if (!target.database || !Array.isArray(roles) || !roles.length ||
+        roles.some(role => role.role !== "readWrite" || role.db !== target.database)) {
+      throw recoveryRequired("MONGO_RUNTIME_SCOPE_UNSAFE");
+    }
     await db.command({ ping: 1 });
     if (writeProbe) {
       const probe = db.collection("__oon_runtime_probe");
@@ -121,7 +151,7 @@ async function waitForMongoUri(
       }
     }
   }
-  const reason = lastError?.codeName || lastError?.code || lastError?.name;
+  const reason = [13, 18].includes(lastError?.code) ? lastError.code : undefined;
   throw new Error(
     `A credencial derivada do MongoDB não passou no teste de leitura e escrita${
       reason ? ` (${reason})` : ""
@@ -129,15 +159,23 @@ async function waitForMongoUri(
   );
 }
 
-async function provisionNativeMongo({ adminUri, appCode, environment }) {
-  const { dbName, username } = mongoIdentity(appCode, environment);
+async function provisionNativeMongo({ adminUri, appCode, environment, instanceUid }, deps = {}) {
+  const identity = mongoIdentity(appCode, environment, { instanceUid });
+  const { dbName, username } = identity;
   const password = randomSecret(30);
-  const client = new mongo.MongoClient(adminUri, {
-    serverSelectionTimeoutMS: 15000,
+  const MongoClient = deps.MongoClient || defaultMongoClient();
+  const client = new MongoClient(adminUri, {
+    serverSelectionTimeoutMS: 15000, connectTimeoutMS: 15000, maxPoolSize: 2,
   });
-  await client.connect();
   try {
+    await client.connect();
     const db = client.db(dbName);
+    const existing = await db.command({ usersInfo: username });
+    if (!Array.isArray(existing.users) || existing.users.length) throw recoveryRequired();
+    const mongoUri = buildRuntimeMongoUri({ adminUri, username, password, dbName, authSource: dbName });
+    if (typeof deps.persistCredential !== "function") throw recoveryRequired("MONGO_CREDENTIAL_PERSISTENCE_REQUIRED");
+    // Capture before createUser: loss of its response never requires password rotation.
+    await deps.persistCredential(mongoUri);
     try {
       await db.command({
         createUser: username,
@@ -150,11 +188,7 @@ async function provisionNativeMongo({ adminUri, appCode, environment }) {
         error.code === 51003 ||
         /already exists/i.test(error.message);
       if (!alreadyExists) throw error;
-      await db.command({
-        updateUser: username,
-        pwd: password,
-        roles: [{ role: "readWrite", db: dbName }],
-      });
+      throw recoveryRequired();
     }
   } finally {
     await client.close();
@@ -163,6 +197,9 @@ async function provisionNativeMongo({ adminUri, appCode, environment }) {
   return {
     dbName,
     username,
+    ...(identity.mode === "canonical"
+      ? { instanceUid: identity.instanceUid, technicalIdentityVersion: identity.identityVersion }
+      : {}),
     mongoUri: buildRuntimeMongoUri({
       adminUri,
       username,
@@ -191,7 +228,7 @@ async function digitalOceanRequest(
   } = {},
 ) {
   if (!fetchImpl) throw new Error("fetch não disponível para a DigitalOcean API.");
-  const attempts = Math.max(1, Number(retryAttempts) || 3);
+  const attempts = method === "GET" ? Math.max(1, Number(retryAttempts) || 3) : 1;
 
   for (let attempt = 1; attempt <= attempts; attempt += 1) {
     const controller = new AbortController();
@@ -209,6 +246,7 @@ async function digitalOceanRequest(
           },
           body: body ? JSON.stringify(body) : undefined,
           signal: controller.signal,
+          redirect: "error",
         },
       );
     } catch (error) {
@@ -219,7 +257,7 @@ async function digitalOceanRequest(
       if (error.name === "AbortError") {
         throw new Error("Timeout ao acessar a DigitalOcean API.");
       }
-      throw new Error(`Falha ao acessar a DigitalOcean API: ${error.message}`);
+      throw recoveryRequired("MONGO_PROVIDER_REQUEST_FAILED");
     } finally {
       clearTimeout(timeout);
     }
@@ -241,20 +279,8 @@ async function digitalOceanRequest(
       continue;
     }
 
-    const providerMessage = String(payload.message || payload.id || "erro")
-      .replace(/[\r\n]+/g, " ")
-      .slice(0, 300);
-    const providerRequestId = String(payload.request_id || "")
-      .replace(/[^A-Za-z0-9_.:-]/g, "")
-      .slice(0, 120);
-    const error = new Error(
-      `DigitalOcean API rejeitou ${method} ${path}: HTTP ${response.status} (${providerMessage})`
-      + (providerRequestId ? ` [requestId: ${providerRequestId}]` : "")
-      + ".",
-    );
+    const error = recoveryRequired(`MONGO_PROVIDER_HTTP_${response.status}`);
     error.status = response.status;
-    error.payload = payload;
-    error.providerRequestId = providerRequestId || undefined;
     throw error;
   }
 
@@ -273,19 +299,14 @@ async function ensureDigitalOceanDatabase(options, deps) {
   } catch (error) {
     if (error.status === 404) {
       exists = false;
-    } else if (DIGITALOCEAN_SERVER_STATUS.has(error.status)) {
-      const listed = await digitalOceanRequest(
-        { ...options, path: "/dbs", expected: [200] },
-        deps,
-      );
-      exists = Array.isArray(listed.payload.dbs)
-        && listed.payload.dbs.some((item) => item?.name === options.dbName);
     } else {
       throw error;
     }
   }
   if (exists) return;
 
+  // Refuse a pre-existing/ambiguous user before creating any database resource.
+  await assertDigitalOceanUserAbsent(options, deps);
   await digitalOceanRequest(
     {
       ...options,
@@ -307,70 +328,35 @@ function digitalOceanUserSettings(dbName) {
   };
 }
 
-async function provisionDigitalOceanUser(options, deps) {
-  const userPath = `/users/${encodeURIComponent(options.username)}`;
-  let exists = false;
+async function assertDigitalOceanUserAbsent(options, deps) {
   try {
     await digitalOceanRequest(
-      { ...options, path: userPath, expected: [200] },
+      { ...options, path: `/users/${encodeURIComponent(options.username)}`, expected: [200] },
       deps,
     );
-    exists = true;
   } catch (error) {
-    if (error.status === 404) {
-      exists = false;
-    } else if (DIGITALOCEAN_SERVER_STATUS.has(error.status)) {
-      const listed = await digitalOceanRequest(
-        { ...options, path: "/users", expected: [200] },
-        deps,
-      );
-      exists = Array.isArray(listed.payload.users)
-        && listed.payload.users.some(
-          (item) => item?.name === options.username,
-        );
-    } else {
-      throw error;
-    }
+    if (error.status === 404) return;
+    throw error;
   }
+  throw recoveryRequired();
+}
 
-  const settings = digitalOceanUserSettings(options.dbName);
-  let result;
-  if (!exists) {
-    result = await digitalOceanRequest(
-      {
-        ...options,
-        path: "/users",
-        method: "POST",
-        body: { name: options.username, settings },
-        expected: [201, 202],
-      },
-      deps,
-    );
-  } else {
-    await digitalOceanRequest(
-      {
-        ...options,
-        path: userPath,
-        method: "PUT",
-        body: { settings },
-        expected: [200, 202],
-      },
-      deps,
-    );
-    result = await digitalOceanRequest(
-      {
-        ...options,
-        path: `${userPath}/reset_auth`,
-        method: "POST",
-        body: {},
-        expected: [200, 201, 202],
-      },
-      deps,
-    );
-  }
+async function provisionDigitalOceanUser(options, deps) {
+  // Recheck after database creation: another publisher may have created the user.
+  await assertDigitalOceanUserAbsent(options, deps);
+  const result = await digitalOceanRequest(
+    {
+      ...options,
+      path: "/users",
+      method: "POST",
+      body: { name: options.username, settings: digitalOceanUserSettings(options.dbName) },
+      expected: [201, 202],
+    },
+    deps,
+  );
 
   const user = result.payload.user;
-  if (!user?.password) {
+  if (user?.name !== options.username || typeof user?.password !== "string" || !user.password) {
     throw new Error(
       "DigitalOcean API não retornou a senha do usuário. O token precisa do escopo database:view_credentials.",
     );
@@ -383,6 +369,7 @@ async function provisionDigitalOceanMongo(
     adminUri,
     appCode,
     environment,
+    instanceUid,
     digitalOceanToken,
     digitalOceanClusterId,
   },
@@ -399,23 +386,28 @@ async function provisionDigitalOceanMongo(
     );
   }
 
-  const { dbName, username } = mongoIdentity(appCode, environment);
+  const identity = mongoIdentity(appCode, environment, { instanceUid });
+  const { dbName, username } = identity;
   const apiOptions = {
     token: digitalOceanToken,
     clusterId: digitalOceanClusterId,
     dbName,
     username,
   };
+  if (typeof deps.persistCredential !== "function") throw recoveryRequired("MONGO_CREDENTIAL_PERSISTENCE_REQUIRED");
+  // Validate URI construction before any provider mutation.
+  buildRuntimeMongoUri({ adminUri, username, password: "preflight", dbName, authSource: "admin" });
   await ensureDigitalOceanDatabase(apiOptions, deps);
   const user = await provisionDigitalOceanUser(apiOptions, deps);
   const mongoUri = buildRuntimeMongoUri({
     adminUri,
-    username: user.name || username,
+    username,
     password: user.password,
     dbName,
     authSource: "admin",
   });
 
+  await deps.persistCredential(mongoUri);
   await waitForMongoUri(mongoUri, {
     validate: deps.validateMongoUri || validateMongoUri,
     attempts: deps.validationAttempts,
@@ -424,7 +416,10 @@ async function provisionDigitalOceanMongo(
 
   return {
     dbName,
-    username: user.name || username,
+    username,
+    ...(identity.mode === "canonical"
+      ? { instanceUid: identity.instanceUid, technicalIdentityVersion: identity.identityVersion }
+      : {}),
     mongoUri,
     provider: "digitalocean",
   };
@@ -435,7 +430,7 @@ async function provisionMongo(options, deps = {}) {
   if (provider === "digitalocean") {
     return provisionDigitalOceanMongo(options, deps);
   }
-  const result = await provisionNativeMongo(options);
+  const result = await provisionNativeMongo(options, deps);
   await waitForMongoUri(result.mongoUri, {
     validate: deps.validateMongoUri || validateMongoUri,
     attempts: deps.validationAttempts,
@@ -445,10 +440,10 @@ async function provisionMongo(options, deps = {}) {
 }
 
 module.exports = {
+  recoveryRequired, parseMongoUri, assertMongoIdentity,
   DIGITALOCEAN_API,
   DIGITALOCEAN_HOST_SUFFIX,
   DIGITALOCEAN_RETRYABLE_STATUS,
-  DIGITALOCEAN_SERVER_STATUS,
   mongoIdentity,
   mongoHost,
   resolveMongoProvisioner,

package/src/delivery/runtime.js

@@ -4,7 +4,9 @@ const crypto = require("node:crypto");
 const { spawnSync } = require("node:child_process");
 const { kubectl } = require("./command");
 const { validateInfraFromCluster } = require("../deploy/contracts/infra-contract");
-const { provisionMongo, validateMongoUri } = require("./mongoProvisioning");
+const { resolveMongoCredential } = require("./mongoCredentialLifecycle");
+const { provisionMongo, validateMongoUri, mongoIdentity, recoveryRequired } = require("./mongoProvisioning");
+const { canonicalizeDeliveryContext } = require("./technicalIdentity");
 
 const RESOURCE_PROFILES = {
   nano: { cpuRequest: "50m", cpuLimit: "250m", memoryRequest: "96Mi", memoryLimit: "256Mi" },
@@ -31,29 +33,45 @@ function applyYaml(yaml) {
 }
 function readSecret(namespace, name, key) {
   try {
-    const value = kubectl(["-n", namespace, "get", "secret", name, "-o", `jsonpath={.data.${key}}`], { capture: true });
+    const value = kubectl(["-n", namespace, "get", "secret", name, "--ignore-not-found", "-o", `jsonpath={.data.${key}}`], { capture: true });
     return value ? Buffer.from(value, "base64").toString("utf8") : null;
-  } catch { return null; }
+  } catch { throw recoveryRequired("MONGO_SECRET_READ_FAILED"); }
+}
+
+function canonicalRuntimeContext(context) {
+  return canonicalizeDeliveryContext(context);
+}
+
+function identityLabels(identity) {
+  if (identity.mode !== "canonical") return "";
+  return `\n    oon.runtime/instance-uid: ${identity.instanceUid}\n    oon.runtime/identity-version: \"${identity.version}\"`;
+}
+
+function podIdentityLabels(identity) {
+  if (identity.mode !== "canonical") return "";
+  return `\n        oon.runtime/instance-uid: ${identity.instanceUid}\n        oon.runtime/identity-version: \"${identity.version}\"`;
 }
 
 function baselineManifest({ context }) {
+  const normalized = canonicalRuntimeContext(context);
+  const identity = normalized.deliveryTechnicalIdentity;
   return `apiVersion: v1
 kind: Namespace
 metadata:
-  name: ${context.namespace}
+  name: ${normalized.namespace}
   labels:
-    oon.dev/app-code: ${context.appCode}
-    oon.dev/environment: ${context.environment}
-    app.kubernetes.io/managed-by: oon-platform
+    oon.dev/app-code: ${normalized.appCode}
+    oon.dev/environment: ${normalized.environment}
+    app.kubernetes.io/managed-by: oon-platform${identityLabels(identity)}
 ---
 apiVersion: v1
 kind: ServiceAccount
-metadata: { name: oon-runtime, namespace: ${context.namespace} }
+metadata: { name: ${identity.serviceAccount}, namespace: ${normalized.namespace} }
 automountServiceAccountToken: false
 ---
 apiVersion: v1
 kind: LimitRange
-metadata: { name: oon-runtime-defaults, namespace: ${context.namespace} }
+metadata: { name: oon-runtime-defaults, namespace: ${normalized.namespace} }
 spec:
   limits:
     - type: Container
@@ -62,13 +80,13 @@ spec:
 ---
 apiVersion: v1
 kind: ResourceQuota
-metadata: { name: oon-runtime-quota, namespace: ${context.namespace} }
+metadata: { name: oon-runtime-quota, namespace: ${normalized.namespace} }
 spec:
   hard: { requests.cpu: "2", requests.memory: 2Gi, limits.cpu: "4", limits.memory: 4Gi, pods: "20", services: "10" }
 ---
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
-metadata: { name: oon-runtime-baseline, namespace: ${context.namespace} }
+metadata: { name: oon-runtime-baseline, namespace: ${normalized.namespace} }
 spec:
   podSelector: {}
   policyTypes: [Ingress, Egress]
@@ -82,35 +100,37 @@ spec:
 }
 
 function runtimeManifest({ context, infra, imageRef, profile = "small" }) {
+  const normalized = canonicalRuntimeContext(context);
+  const identity = normalized.deliveryTechnicalIdentity;
   const resources = RESOURCE_PROFILES[profile] || RESOURCE_PROFILES.small;
-  const releaseLabel = kubernetesLabelValue(context.releaseId);
-  const releaseAnnotation = JSON.stringify(String(context.releaseId));
+  const releaseLabel = kubernetesLabelValue(normalized.releaseId);
+  const releaseAnnotation = JSON.stringify(String(normalized.releaseId));
   return `apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: ${context.appCode}
-  namespace: ${context.namespace}
+  name: ${normalized.appCode}
+  namespace: ${normalized.namespace}
 spec:
   replicas: 1
   selector:
-    matchLabels: { app.kubernetes.io/name: ${context.appCode} }
+    matchLabels: { app.kubernetes.io/name: ${normalized.appCode} }
   template:
     metadata:
       labels:
-        app.kubernetes.io/name: ${context.appCode}
+        app.kubernetes.io/name: ${normalized.appCode}
         app.kubernetes.io/part-of: oon-central
-        oon.dev/release-id: ${releaseLabel}
+        oon.dev/release-id: ${releaseLabel}${podIdentityLabels(identity)}
       annotations:
         oon.dev/release-id: ${releaseAnnotation}
     spec:
-      serviceAccountName: oon-runtime
+      serviceAccountName: ${identity.serviceAccount}
       imagePullSecrets: [{ name: ${infra.REGISTRY_PULL_SECRET_NAME || "ghcr-oon"} }]
       containers:
         - name: central
           image: ${imageRef}
           imagePullPolicy: IfNotPresent
           ports: [{ name: http, containerPort: 8080 }]
-          envFrom: [{ secretRef: { name: oon-runtime } }]
+          envFrom: [{ secretRef: { name: ${identity.secret} } }]
           resources:
             requests: { cpu: ${resources.cpuRequest}, memory: ${resources.memoryRequest} }
             limits: { cpu: ${resources.cpuLimit}, memory: ${resources.memoryLimit} }
@@ -123,28 +143,28 @@ spec:
 ---
 apiVersion: v1
 kind: Service
-metadata: { name: ${context.appCode}, namespace: ${context.namespace} }
+metadata: { name: ${normalized.appCode}, namespace: ${normalized.namespace} }
 spec:
-  selector: { app.kubernetes.io/name: ${context.appCode} }
+  selector: { app.kubernetes.io/name: ${normalized.appCode} }
   ports: [{ name: http, port: 80, targetPort: http }]
 ---
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
-  name: ${context.appCode}
-  namespace: ${context.namespace}
+  name: ${normalized.appCode}
+  namespace: ${normalized.namespace}
   annotations: { cert-manager.io/cluster-issuer: ${infra.CLUSTER_ISSUER} }
 spec:
   ingressClassName: ${infra.INGRESS_CLASS}
-  tls: [{ hosts: [${context.hostname}], secretName: ${context.appCode}-tls }]
+  tls: [{ hosts: [${normalized.hostname}], secretName: ${identity.tlsSecret} }]
   rules:
-    - host: ${context.hostname}
+    - host: ${normalized.hostname}
       http:
         paths:
           - path: /
             pathType: Prefix
             backend:
-              service: { name: ${context.appCode}, port: { name: http } }
+              service: { name: ${normalized.appCode}, port: { name: http } }
 `;
 }
 
@@ -158,27 +178,41 @@ function copyPullSecret(namespace, infra) {
   } catch (error) { if (!/not found/i.test(error.message)) throw error; }
 }
 
-function applyRuntimeSecret({ context, mongoUri, encryptionKey, extraSecrets = {} }) {
+function applyRuntimeSecret({ context, mongoUri, encryptionKey, extraSecrets = {}, record, writeRecord }) {
+  const normalized = canonicalRuntimeContext(context);
+  const identity = normalized.deliveryTechnicalIdentity;
   const literals = {
+    ...extraSecrets,
     MONGO_URI: mongoUri,
     NODE_ENV: "production",
-    APP_ENVIRONMENT: context.environment,
-    APP_CODE: context.appCode,
-    PUBLIC_APP_URL: context.publicUrl,
-    CENTRAL_ATIVACAO_URL: context.activationApiUrl,
-    CENTRAL_ATIVACAO_API_URL: context.activationApiUrl,
+    APP_ENVIRONMENT: normalized.environment,
+    APP_CODE: normalized.appCode,
+    PUBLIC_APP_URL: normalized.publicUrl,
+    CENTRAL_ATIVACAO_URL: normalized.activationApiUrl,
+    CENTRAL_ATIVACAO_API_URL: normalized.activationApiUrl,
     INSTANCE_CREDENTIAL_ENCRYPTION_KEY: encryptionKey,
-    ...extraSecrets,
+    ...(identity.mode === "canonical"
+      ? {
+        OON_INSTANCE_UID: identity.instanceUid,
+        OON_TECHNICAL_IDENTITY_VERSION: String(identity.version),
+      }
+      : {}),
   };
-  const args = ["-n", context.namespace, "create", "secret", "generic", "oon-runtime"];
-  for (const [key, value] of Object.entries(literals)) args.push(`--from-literal=${key}=${value}`);
-  args.push("--dry-run=client", "-o", "yaml");
-  applyYaml(kubectl(args, { capture: true }));
+  writeRecord("replace", {
+    ...record,
+    metadata: { ...record.metadata, annotations: {
+      ...record.metadata.annotations, "oon.runtime/mongo-state": "ready",
+    } },
+    data: { ...record.data, ...Object.fromEntries(Object.entries(literals)
+      .map(([key, value]) => [key, Buffer.from(String(value)).toString("base64")])) },
+  });
 }
 
 async function provisionRuntime({ context, extraSecrets = {} }) {
+  const normalized = canonicalRuntimeContext(context);
+  const identity = normalized.deliveryTechnicalIdentity;
   const infra = validateInfraFromCluster().config;
-  applyYaml(baselineManifest({ context, infra }));
+  applyYaml(baselineManifest({ context: normalized, infra }));
 
   const platformNamespace = infra.PLATFORM_NAMESPACE || "oon-system";
   const adminSecretName = infra.MONGO_ADMIN_SECRET_NAME || "oon-mongo-admin";
@@ -205,53 +239,77 @@ async function provisionRuntime({ context, extraSecrets = {} }) {
     "DIGITALOCEAN_DATABASE_CLUSTER_ID",
   );
 
-  let mongoUri = readSecret(context.namespace, "oon-runtime", "MONGO_URI");
-  let databaseName = "";
-  let credentialRotated = false;
-
-  if (mongoUri) {
-    try {
-      await validateMongoUri(mongoUri);
-    } catch (error) {
-      console.warn(
-        "A credencial MongoDB persistida não passou na validação; " +
-          "ela será reprovisionada.",
-      );
-      mongoUri = null;
-      credentialRotated = true;
-    }
-  }
-
-  if (!mongoUri) {
-    const provisioned = await provisionMongo({
-      adminUri,
-      appCode: context.appCode,
-      environment: context.environment,
-      provisioner: mongoProvisioner,
-      digitalOceanToken,
-      digitalOceanClusterId,
+  // Read errors are distinct from confirmed absence. Never provision on a failed GET.
+  let record;
+  try {
+    const raw = kubectl(["-n", normalized.namespace, "get", "secret", identity.secret,
+      "--ignore-not-found", "-o", "json"], { capture: true });
+    record = raw ? JSON.parse(raw) : null;
+  } catch { throw recoveryRequired("MONGO_SECRET_READ_FAILED"); }
+  const decode = (key) => record?.data?.[key]
+    ? Buffer.from(record.data[key], "base64").toString("utf8") : null;
+  const encryptionKey = record === null ? randomSecret(48) : decode("INSTANCE_CREDENTIAL_ENCRYPTION_KEY");
+  if (!encryptionKey) throw recoveryRequired("MONGO_ENCRYPTION_KEY_MISSING");
+  const writeRecord = (operation, value) => {
+    // Secrets travel through stdin and captured output, never inherited stderr/argv.
+    const result = spawnSync("kubectl", [operation, "-f", "-", "-o", "json"], {
+      input: JSON.stringify(value), encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
     });
-    mongoUri = provisioned.mongoUri;
-    databaseName = provisioned.dbName;
-    credentialRotated = true;
-  }
-
-  const encryptionKey =
-    readSecret(
-      context.namespace,
-      "oon-runtime",
-      "INSTANCE_CREDENTIAL_ENCRYPTION_KEY",
-    ) || randomSecret(48);
-  applyRuntimeSecret({ context, mongoUri, encryptionKey, extraSecrets });
-  return { infra, databaseName, credentialRotated };
+    if (result.status !== 0) throw recoveryRequired("MONGO_SECRET_WRITE_FAILED");
+    try { record = JSON.parse(result.stdout); }
+    catch { throw recoveryRequired("MONGO_SECRET_RESPONSE_INVALID"); }
+    if (!record?.metadata?.resourceVersion) throw recoveryRequired("MONGO_SECRET_RESPONSE_INVALID");
+  };
+  const mongo = await resolveMongoCredential({
+    identity: mongoIdentity(normalized.appCode, normalized.environment,
+      identity.mode === "canonical" ? { instanceUid: identity.instanceUid } : {}),
+    read: async () => record === null ? null : { mongoUri: decode("MONGO_URI") },
+    begin: async () => writeRecord("create", {
+      apiVersion: "v1", kind: "Secret", type: "Opaque",
+      metadata: { name: identity.secret, namespace: normalized.namespace,
+        annotations: { "oon.runtime/mongo-state": "provisioning" } },
+      data: { INSTANCE_CREDENTIAL_ENCRYPTION_KEY: Buffer.from(encryptionKey).toString("base64") },
+    }),
+    persist: async (uri) => writeRecord("replace", {
+      ...record,
+      metadata: { ...record.metadata, annotations: {
+        ...record.metadata.annotations, "oon.runtime/mongo-state": "credential-captured",
+      } },
+      data: { ...record.data, MONGO_URI: Buffer.from(uri).toString("base64") },
+    }),
+    provision: (persistCredential) => provisionMongo({
+      adminUri, appCode: normalized.appCode, environment: normalized.environment,
+      ...(identity.mode === "canonical" ? { instanceUid: identity.instanceUid } : {}),
+      provisioner: mongoProvisioner, digitalOceanToken, digitalOceanClusterId,
+    }, { persistCredential }),
+    validate: validateMongoUri,
+  });
+  const mongoUri = mongo.mongoUri;
+  const databaseName = mongoIdentity(normalized.appCode, normalized.environment,
+    identity.mode === "canonical" ? { instanceUid: identity.instanceUid } : {}).dbName;
+  const credentialRotated = false;
+  applyRuntimeSecret({ context: normalized, mongoUri, encryptionKey, extraSecrets, record, writeRecord });
+  return {
+    infra,
+    databaseName,
+    credentialRotated,
+    ...(identity.mode === "canonical" ? { technicalIdentity: identity } : {}),
+  };
 }
 
 function deployRuntime({ context, infra, imageDigest, resourceProfile = "small" }) {
-  copyPullSecret(context.namespace, infra);
-  const imageRef = `${context.imageRepository}@${imageDigest}`;
-  applyYaml(runtimeManifest({ context, infra, imageRef, profile: resourceProfile }));
-  kubectl(["-n", context.namespace, "rollout", "status", `deployment/${context.appCode}`, "--timeout=10m"]);
-  return { infraVersion: infra.INFRA_SCHEMA_VERSION, imageRef };
+  const normalized = canonicalRuntimeContext(context);
+  copyPullSecret(normalized.namespace, infra);
+  const imageRef = `${normalized.imageRepository}@${imageDigest}`;
+  applyYaml(runtimeManifest({ context: normalized, infra, imageRef, profile: resourceProfile }));
+  kubectl(["-n", normalized.namespace, "rollout", "status", `deployment/${normalized.appCode}`, "--timeout=10m"]);
+  return {
+    infraVersion: infra.INFRA_SCHEMA_VERSION,
+    imageRef,
+    ...(normalized.deliveryTechnicalIdentity.mode === "canonical"
+      ? { technicalIdentity: normalized.deliveryTechnicalIdentity }
+      : {}),
+  };
 }
 
 async function waitHttp(url, { timeoutMs = 300000, expectedStatus = 200 } = {}) {
@@ -269,19 +327,20 @@ async function waitHttp(url, { timeoutMs = 300000, expectedStatus = 200 } = {})
 }
 
 async function activateMember(context) {
-  const statusResponse = await waitHttp(`${context.publicUrl}/api/ativacao/status`);
+  const normalized = canonicalRuntimeContext(context);
+  const statusResponse = await waitHttp(`${normalized.publicUrl}/api/ativacao/status`);
   const status = await statusResponse.json();
   if (status.status === "ativa") return { alreadyActive: true, instanceId: status.instanceId };
-  if (!context.activationCode) throw new Error("Instância não está ativa e não há código de ativação autorizado.");
-  const response = await fetch(`${context.publicUrl}/api/ativacao/concluir`, {
+  if (!normalized.activationCode) throw new Error("Instância não está ativa e não há código de ativação autorizado.");
+  const response = await fetch(`${normalized.publicUrl}/api/ativacao/concluir`, {
     method: "POST",
-    headers: { "Content-Type": "application/json", "Idempotency-Key": context.releaseId },
+    headers: { "Content-Type": "application/json", "Idempotency-Key": normalized.releaseId },
     body: JSON.stringify({
-      codigoAtivacao: context.activationCode,
-      nomeInstancia: `${context.appCode} dev`,
+      codigoAtivacao: normalized.activationCode,
+      nomeInstancia: `${normalized.appCode} dev`,
       parametrosGlobais: {
-        nomeInstancia: `${context.appCode} dev`, ambiente: context.environment,
-        urlPublica: context.publicUrl, emailAdministrativo: context.administrativeEmail,
+        nomeInstancia: `${normalized.appCode} dev`, ambiente: normalized.environment,
+        urlPublica: normalized.publicUrl, emailAdministrativo: normalized.administrativeEmail,
         idioma: "pt-BR", timezone: "America/Sao_Paulo", moeda: "BRL", pais: "BR", formatoData: "DD/MM/YYYY",
       },
       parametrosAplicacao: {},
@@ -292,4 +351,18 @@ async function activateMember(context) {
   return data;
 }
 
-module.exports = { RESOURCE_PROFILES, randomSecret, dnsLabel, kubernetesLabelValue, provisionMongo, validateMongoUri, baselineManifest, runtimeManifest, provisionRuntime, deployRuntime, waitHttp, activateMember };
+module.exports = {
+  RESOURCE_PROFILES,
+  randomSecret,
+  dnsLabel,
+  kubernetesLabelValue,
+  canonicalRuntimeContext,
+  provisionMongo,
+  validateMongoUri,
+  baselineManifest,
+  runtimeManifest,
+  provisionRuntime,
+  deployRuntime,
+  waitHttp,
+  activateMember,
+};

package/src/delivery/technicalIdentity.js

@@ -0,0 +1,140 @@
+"use strict";
+
+const technical = require("../core/technicalIdentity");
+
+const SUPPORTED_DELIVERY_IDENTITY_VERSION = 1;
+const CANONICAL_FIELDS = Object.freeze([
+  "version",
+  "appCode",
+  "instanceUid",
+  "environment",
+  "resourceBase",
+  "namespace",
+  "database",
+  "mongoUsername",
+  "serviceAccount",
+  "secret",
+  "provisionJob",
+  "frontendDnsLabel",
+  "backendDnsLabel",
+  "tlsSecret",
+]);
+const CANONICAL_SIGNAL_FIELDS = Object.freeze([
+  "instanceUid",
+  "technicalIdentityVersion",
+  "technicalInstanceId",
+  "technicalIdentity",
+]);
+
+function deliveryIdentityError(code, message, details = {}) {
+  const error = new Error(message);
+  error.name = "DeliveryTechnicalIdentityError";
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+function hasOwn(object, field) {
+  return Object.prototype.hasOwnProperty.call(object || {}, field);
+}
+
+function hasCanonicalIdentitySignal(context = {}) {
+  return CANONICAL_SIGNAL_FIELDS.some((field) => hasOwn(context, field));
+}
+
+function legacyDeliveryIdentity(context = {}) {
+  return Object.freeze({
+    mode: "legacy",
+    version: 0,
+    appCode: String(context.appCode || ""),
+    environment: String(context.environment || ""),
+    namespace: String(context.namespace || ""),
+    serviceAccount: "oon-runtime",
+    secret: "oon-runtime",
+    tlsSecret: `${String(context.appCode || "")}-tls`,
+  });
+}
+
+function assertProjection(canonical, context = {}) {
+  const mismatches = [];
+  if (context.namespace != null && String(context.namespace) !== canonical.namespace) {
+    mismatches.push("namespace");
+  }
+
+  if (hasOwn(context, "technicalIdentity")) {
+    const projected = context.technicalIdentity;
+    if (!projected || typeof projected !== "object" || Array.isArray(projected)) {
+      throw deliveryIdentityError(
+        "DELIVERY_TECHNICAL_IDENTITY_PROJECTION_INVALID",
+        "A projeção da identidade técnica do delivery é inválida.",
+      );
+    }
+    for (const field of CANONICAL_FIELDS) {
+      if (projected[field] == null) continue;
+      if (String(projected[field]) !== String(canonical[field])) mismatches.push(field);
+    }
+  }
+
+  if (mismatches.length) {
+    throw deliveryIdentityError(
+      "DELIVERY_TECHNICAL_IDENTITY_MISMATCH",
+      "O contexto de delivery diverge da identidade técnica canônica.",
+      { mismatches: [...new Set(mismatches)] },
+    );
+  }
+}
+
+function resolveDeliveryTechnicalIdentity(context = {}, { requireCanonical = false } = {}) {
+  if (!hasCanonicalIdentitySignal(context)) {
+    if (requireCanonical) {
+      throw deliveryIdentityError(
+        "DELIVERY_TECHNICAL_IDENTITY_REQUIRED",
+        "O contexto de delivery exige identidade técnica canônica.",
+      );
+    }
+    return legacyDeliveryIdentity(context);
+  }
+
+  if (context.instanceUid == null || context.technicalIdentityVersion == null) {
+    throw deliveryIdentityError(
+      "DELIVERY_TECHNICAL_IDENTITY_INCOMPLETE",
+      "O contexto de delivery possui identidade técnica parcial.",
+    );
+  }
+  if (Number(context.technicalIdentityVersion) !== SUPPORTED_DELIVERY_IDENTITY_VERSION) {
+    throw deliveryIdentityError(
+      "DELIVERY_TECHNICAL_IDENTITY_VERSION_UNSUPPORTED",
+      "A versão da identidade técnica do delivery não é suportada.",
+      { received: context.technicalIdentityVersion, supported: SUPPORTED_DELIVERY_IDENTITY_VERSION },
+    );
+  }
+
+  const canonical = technical.technicalIdentity({
+    appCode: context.appCode,
+    instanceUid: context.instanceUid,
+    environment: context.environment,
+  });
+  assertProjection(canonical, context);
+  return Object.freeze({ mode: "canonical", ...canonical });
+}
+
+function canonicalizeDeliveryContext(context = {}, options = {}) {
+  const identity = resolveDeliveryTechnicalIdentity(context, options);
+  if (identity.mode !== "canonical") {
+    return Object.freeze({ ...context, deliveryTechnicalIdentity: identity });
+  }
+  return Object.freeze({
+    ...context,
+    namespace: identity.namespace,
+    deliveryTechnicalIdentity: identity,
+  });
+}
+
+module.exports = Object.freeze({
+  CANONICAL_FIELDS,
+  CANONICAL_SIGNAL_FIELDS,
+  SUPPORTED_DELIVERY_IDENTITY_VERSION,
+  canonicalizeDeliveryContext,
+  hasCanonicalIdentitySignal,
+  resolveDeliveryTechnicalIdentity,
+});