@oondemand/oon-core-back 0.6.7 → 0.6.9

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.7",
+  "version": "0.6.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",

package/src/core/technicalIdentity.js

@@ -0,0 +1,174 @@
+"use strict";
+
+const crypto = require("node:crypto");
+
+const APP_CODE_MAX_LENGTH = 24;
+const APP_CODE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,22}[a-z0-9])?$/;
+const INSTANCE_UID_ALPHABET = "23456789abcdefghjkmnopqrstuvwxyz";
+const INSTANCE_UID_LENGTH = 16;
+const INSTANCE_UID_BYTES = 10;
+const INSTANCE_UID_PATTERN = /^[23456789abcdefghjkmnopqrstuvwxyz]{16}$/;
+
+const ENVIRONMENT_TOKENS = Object.freeze({
+  desenvolvimento: "dev",
+  homologacao: "hml",
+  producao: "prod",
+  dev: "dev",
+  hml: "hml",
+  prod: "prod",
+});
+
+class TechnicalIdentityError extends Error {
+  constructor(message, code, details = {}) {
+    super(message);
+    this.name = "TechnicalIdentityError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function assertAppCode(value) {
+  const appCode = typeof value === "string" ? value : "";
+  if (!APP_CODE_PATTERN.test(appCode)) {
+    throw new TechnicalIdentityError(
+      `appCode deve seguir ${APP_CODE_PATTERN} e possuir no máximo ${APP_CODE_MAX_LENGTH} caracteres ASCII.`,
+      "TECHNICAL_APP_CODE_INVALID",
+      { appCode },
+    );
+  }
+  return appCode;
+}
+
+function assertInstanceUid(value) {
+  const instanceUid = typeof value === "string" ? value : "";
+  if (!INSTANCE_UID_PATTERN.test(instanceUid)) {
+    throw new TechnicalIdentityError(
+      `instanceUid deve possuir ${INSTANCE_UID_LENGTH} caracteres no alfabeto canônico.`,
+      "TECHNICAL_INSTANCE_UID_INVALID",
+      { instanceUid },
+    );
+  }
+  return instanceUid;
+}
+
+function environmentToken(value) {
+  const environment = String(value || "").trim().toLowerCase();
+  const hasEnvironment = Object.prototype.hasOwnProperty.call(ENVIRONMENT_TOKENS, environment);
+  const token = hasEnvironment ? ENVIRONMENT_TOKENS[environment] : null;
+  if (!token) {
+    throw new TechnicalIdentityError(
+      "Ambiente técnico inválido.",
+      "TECHNICAL_ENVIRONMENT_INVALID",
+      { environment },
+    );
+  }
+  return token;
+}
+
+function encodeInstanceUid(bytes) {
+  const buffer = Buffer.from(bytes || []);
+  if (buffer.length !== INSTANCE_UID_BYTES) {
+    throw new TechnicalIdentityError(
+      `instanceUid exige exatamente ${INSTANCE_UID_BYTES} bytes aleatórios.`,
+      "TECHNICAL_INSTANCE_UID_RANDOM_BYTES_INVALID",
+      { receivedBytes: buffer.length },
+    );
+  }
+
+  let accumulator = 0;
+  let bits = 0;
+  let output = "";
+  for (const byte of buffer) {
+    accumulator = (accumulator << 8) | byte;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      output += INSTANCE_UID_ALPHABET[(accumulator >> bits) & 31];
+      accumulator &= (1 << bits) - 1;
+    }
+  }
+
+  if (bits !== 0 || output.length !== INSTANCE_UID_LENGTH) {
+    throw new TechnicalIdentityError(
+      "Falha ao codificar instanceUid de 80 bits.",
+      "TECHNICAL_INSTANCE_UID_ENCODING_INVALID",
+    );
+  }
+  return output;
+}
+
+function generateInstanceUid(randomBytes = crypto.randomBytes) {
+  if (typeof randomBytes !== "function") {
+    throw new TypeError("randomBytes deve ser uma função.");
+  }
+  return encodeInstanceUid(randomBytes(INSTANCE_UID_BYTES));
+}
+
+function technicalIdentity({ appCode, instanceUid, environment }) {
+  const canonicalAppCode = assertAppCode(appCode);
+  const canonicalInstanceUid = assertInstanceUid(instanceUid);
+  const env = environmentToken(environment);
+  const base = `${canonicalAppCode}-${canonicalInstanceUid}-${env}`;
+  const database = `${canonicalAppCode}_${canonicalInstanceUid}_${env}`;
+  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,
+    database: database.length,
+    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) {
+    throw new TechnicalIdentityError(
+      "Identidade técnica excede o orçamento DNS/Kubernetes de 63 caracteres.",
+      "TECHNICAL_IDENTITY_BUDGET_EXCEEDED",
+      { resource: invalidLength[0], length: invalidLength[1] },
+    );
+  }
+
+  return Object.freeze({
+    version: 1,
+    appCode: canonicalAppCode,
+    instanceUid: canonicalInstanceUid,
+    environment: env,
+    resourceBase: base,
+    namespace: base,
+    database,
+    mongoUsername,
+    serviceAccount,
+    secret,
+    provisionJob,
+    frontendDnsLabel,
+    backendDnsLabel,
+    tlsSecret,
+  });
+}
+
+module.exports = Object.freeze({
+  APP_CODE_MAX_LENGTH,
+  APP_CODE_PATTERN,
+  INSTANCE_UID_ALPHABET,
+  INSTANCE_UID_LENGTH,
+  INSTANCE_UID_BYTES,
+  INSTANCE_UID_PATTERN,
+  ENVIRONMENT_TOKENS,
+  TechnicalIdentityError,
+  assertAppCode,
+  assertInstanceUid,
+  environmentToken,
+  encodeInstanceUid,
+  generateInstanceUid,
+  technicalIdentity,
+});

package/src/delivery/mongoProvisioning.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const { mongo } = require("mongoose");
+const { technicalIdentity } = require("../core/technicalIdentity");
 
 const DIGITALOCEAN_API = "https://api.digitalocean.com/v2";
 const DIGITALOCEAN_HOST_SUFFIX = ".mongo.ondigitalocean.com";
@@ -24,8 +25,19 @@ 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),
   };
@@ -129,8 +141,9 @@ async function waitForMongoUri(
   );
 }
 
-async function provisionNativeMongo({ adminUri, appCode, environment }) {
-  const { dbName, username } = mongoIdentity(appCode, environment);
+async function provisionNativeMongo({ adminUri, appCode, environment, instanceUid }) {
+  const identity = mongoIdentity(appCode, environment, { instanceUid });
+  const { dbName, username } = identity;
   const password = randomSecret(30);
   const client = new mongo.MongoClient(adminUri, {
     serverSelectionTimeoutMS: 15000,
@@ -163,6 +176,9 @@ async function provisionNativeMongo({ adminUri, appCode, environment }) {
   return {
     dbName,
     username,
+    ...(identity.mode === "canonical"
+      ? { instanceUid: identity.instanceUid, technicalIdentityVersion: identity.identityVersion }
+      : {}),
     mongoUri: buildRuntimeMongoUri({
       adminUri,
       username,
@@ -383,6 +399,7 @@ async function provisionDigitalOceanMongo(
     adminUri,
     appCode,
     environment,
+    instanceUid,
     digitalOceanToken,
     digitalOceanClusterId,
   },
@@ -399,7 +416,8 @@ 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,
@@ -425,6 +443,9 @@ async function provisionDigitalOceanMongo(
   return {
     dbName,
     username: user.name || username,
+    ...(identity.mode === "canonical"
+      ? { instanceUid: identity.instanceUid, technicalIdentityVersion: identity.identityVersion }
+      : {}),
     mongoUri,
     provider: "digitalocean",
   };
@@ -462,4 +483,4 @@ module.exports = {
   provisionDigitalOceanUser,
   provisionDigitalOceanMongo,
   provisionMongo,
-};
+};

package/src/delivery/runtime.js

@@ -5,6 +5,7 @@ const { spawnSync } = require("node:child_process");
 const { kubectl } = require("./command");
 const { validateInfraFromCluster } = require("../deploy/contracts/infra-contract");
 const { provisionMongo, validateMongoUri } = require("./mongoProvisioning");
+const { canonicalizeDeliveryContext } = require("./technicalIdentity");
 
 const RESOURCE_PROFILES = {
   nano: { cpuRequest: "50m", cpuLimit: "250m", memoryRequest: "96Mi", memoryLimit: "256Mi" },
@@ -36,24 +37,40 @@ function readSecret(namespace, name, key) {
   } catch { return null; }
 }
 
+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 +79,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 +99,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 +142,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 } }
 `;
 }
 
@@ -159,26 +178,36 @@ function copyPullSecret(namespace, infra) {
 }
 
 function applyRuntimeSecret({ context, mongoUri, encryptionKey, extraSecrets = {} }) {
+  const normalized = canonicalRuntimeContext(context);
+  const identity = normalized.deliveryTechnicalIdentity;
   const literals = {
     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,
+    ...(identity.mode === "canonical"
+      ? {
+        OON_INSTANCE_UID: identity.instanceUid,
+        OON_TECHNICAL_IDENTITY_VERSION: String(identity.version),
+      }
+      : {}),
     ...extraSecrets,
   };
-  const args = ["-n", context.namespace, "create", "secret", "generic", "oon-runtime"];
+  const args = ["-n", normalized.namespace, "create", "secret", "generic", identity.secret];
   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 }));
 }
 
 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,7 +234,7 @@ async function provisionRuntime({ context, extraSecrets = {} }) {
     "DIGITALOCEAN_DATABASE_CLUSTER_ID",
   );
 
-  let mongoUri = readSecret(context.namespace, "oon-runtime", "MONGO_URI");
+  let mongoUri = readSecret(normalized.namespace, identity.secret, "MONGO_URI");
   let databaseName = "";
   let credentialRotated = false;
 
@@ -225,8 +254,9 @@ async function provisionRuntime({ context, extraSecrets = {} }) {
   if (!mongoUri) {
     const provisioned = await provisionMongo({
       adminUri,
-      appCode: context.appCode,
-      environment: context.environment,
+      appCode: normalized.appCode,
+      environment: normalized.environment,
+      ...(identity.mode === "canonical" ? { instanceUid: identity.instanceUid } : {}),
       provisioner: mongoProvisioner,
       digitalOceanToken,
       digitalOceanClusterId,
@@ -238,20 +268,32 @@ async function provisionRuntime({ context, extraSecrets = {} }) {
 
   const encryptionKey =
     readSecret(
-      context.namespace,
-      "oon-runtime",
+      normalized.namespace,
+      identity.secret,
       "INSTANCE_CREDENTIAL_ENCRYPTION_KEY",
     ) || randomSecret(48);
-  applyRuntimeSecret({ context, mongoUri, encryptionKey, extraSecrets });
-  return { infra, databaseName, credentialRotated };
+  applyRuntimeSecret({ context: normalized, mongoUri, encryptionKey, extraSecrets });
+  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 +311,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 +335,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,
+});

package/src/index.js

@@ -10,6 +10,7 @@ const tenancy = require("./core/tenancy");
 const GenericError = require("./core/errors/GenericError");
 const { requirePermission } = require("./core/middlewares/permissions");
 const rbacPolicy = require("./core/rbac/policy");
+const technicalIdentity = require("./core/technicalIdentity");
 const capabilities = require("./capabilities");
 const { operationalRequestHeaders } = require("./core/utils/instanceActivation");
 const appManifest = require("./manifest/appManifest");
@@ -75,6 +76,7 @@ module.exports = {
   drainProcessJobs: processRuntime.drainProcessJobs,
   fields,
   capabilities,
+  technicalIdentity,
   operationalRequestHeaders,
   licensing: {
     assertBusinessOperation: require("./core/licensing").assertBusinessOperation,
@@ -85,4 +87,4 @@ module.exports = {
   PdfRenderingError: capabilities.PdfRenderingError,
   TransactionalEmailError: capabilities.TransactionalEmailError,
   GenericError, registry,
-};
+};