@oondemand/oon-core-back 0.6.11 → 0.6.13

package/package.json

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

package/src/delivery/preparedRuntime.js

@@ -0,0 +1,264 @@
+"use strict";
+
+// Explicit prepared-member path. This module never imports the administrative
+// provisioner, reads platform Secrets, or falls back to provisionRuntime.
+const crypto = require("node:crypto");
+const { spawnSync } = require("node:child_process");
+const { performance } = require("node:perf_hooks");
+const { isDeepStrictEqual } = require("node:util");
+const { resolveDeliveryTechnicalIdentity } = require("./technicalIdentity");
+const MEMBERS = new Set(["meus-apps", "oon-workspace", "oon-docs"]);
+const AUTHORITY_API = "https://central-ativacao.oonapps.online/api";
+const ENVIRONMENTS = new Set(["desenvolvimento", "homologacao", "producao"]);
+const OBJECT_ID = /^[a-f0-9]{24}$/;
+const UID = /^[23456789abcdefghjkmnopqrstuvwxyz]{16}$/;
+const VERSION = /^[0-9]+$/;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const PROFILES = Object.freeze({
+  nano: ["50m", "250m", "96Mi", "256Mi"], small: ["100m", "500m", "128Mi", "512Mi"],
+  medium: ["250m", "1", "256Mi", "1Gi"], large: ["500m", "2", "512Mi", "2Gi"],
+});
+function fail(code) { const e = new Error(code); e.code = code; throw e; }
+function demand(value, code) { if (!value) fail(code); }
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map(k => [k, stable(value[k])]));
+  return value;
+}
+const hash = value => crypto.createHash("sha256").update(JSON.stringify(stable(value))).digest("hex");
+const copy = value => JSON.parse(JSON.stringify(value));
+
+function leaseDeadline(value) {
+  const deadline = typeof value === "string" ? Date.parse(value) : NaN;
+  demand(Number.isFinite(deadline) && new Date(deadline).toISOString() === value,
+    "PREPARED_RUNTIME_LEASE_INVALID");
+  return deadline;
+}
+
+// Local freshness only. An in-flight API request may already have committed;
+// expiry never authorizes takeover, rollback or release of an administrative lock.
+function leaseGuard(expiresAt, { now = Date.now, monotonicNow = () => performance.now() } = {}) {
+  const deadline = leaseDeadline(expiresAt), started = now(), monotonicStarted = monotonicNow();
+  demand(Number.isFinite(started) && Number.isFinite(monotonicStarted), "PREPARED_RUNTIME_CLOCK_INVALID");
+  let lastMonotonic = monotonicStarted;
+  return () => {
+    const current = now(), monotonic = monotonicNow();
+    demand(Number.isFinite(current) && Number.isFinite(monotonic) && monotonic >= lastMonotonic,
+      "PREPARED_RUNTIME_CLOCK_INVALID");
+    lastMonotonic = monotonic;
+    // The original remaining budget cannot grow if the wall clock moves back.
+    demand(current < deadline && monotonic - monotonicStarted < deadline - started,
+      "PREPARED_RUNTIME_LEASE_EXPIRED");
+  };
+}
+
+// authority is trusted executor configuration, separate from the member context.
+// Callers must fetch/authorize the context through Central Prod; no browser input.
+function expectedPreparation({ context: c, imageDigest, authority: a }) {
+  demand(c && a && MEMBERS.has(c.appCode) && c.repository === `oondemand/${c.appCode}` &&
+    c.lifecycleMode === "global_singleton" && ENVIRONMENTS.has(c.environment) &&
+    OBJECT_ID.test(c.appId || "") && OBJECT_ID.test(c.technicalInstanceId || "") &&
+    OBJECT_ID.test(c.deploymentId || "") && c.technicalIdentityVersion === 1 &&
+    /^[A-Za-z0-9_-]{1,120}$/.test(c.releaseId || "") && UUID.test(c.leaseId || "") &&
+    typeof c.deploymentToken === "string" && c.deploymentToken.length >= 32 && c.deploymentToken.length <= 8192 &&
+    /^g[a-z0-9-]{1,39}$/.test(a.installationId || "") && UID.test(a.instanceUid || "") &&
+    a.apiUrl === AUTHORITY_API && c.activationApiUrl === a.apiUrl && c.instanceUid !== a.instanceUid &&
+    /^sha256:[a-f0-9]{64}$/.test(imageDigest || "") && (!c.imageDigest || c.imageDigest === imageDigest) &&
+    c.imageRepository === `ghcr.io/oondemand/${c.appCode}`, "PREPARED_RUNTIME_CONTEXT_INVALID");
+  leaseDeadline(c.leaseExpiresAt);
+  let id; try { id = resolveDeliveryTechnicalIdentity(c, { requireCanonical: true }); }
+  catch { fail("PREPARED_RUNTIME_IDENTITY_INVALID"); }
+  const frontendHostname = `${id.frontendDnsLabel}.oonapps.online`, backendHostname = `${id.backendDnsLabel}.oonapps.online`;
+  demand(c.namespace === id.namespace && c.frontendHostname === frontendHostname && c.backendHostname === backendHostname &&
+    c.frontendUrl === `https://${frontendHostname}` && c.backendUrl === `https://${backendHostname}/api` &&
+    c.publicUrl === c.frontendUrl && c.hostname === frontendHostname, "PREPARED_RUNTIME_URL_INVALID");
+  const profile = c.resourceProfile || "small";
+  demand(Object.hasOwn(PROFILES, profile), "PREPARED_RUNTIME_PROFILE_INVALID");
+  const binding = { schemaVersion: 2, installationId: a.installationId, authorityInstanceUid: a.instanceUid,
+    authorityApiUrl: a.apiUrl, appId: c.appId, appCode: c.appCode, technicalInstanceId: c.technicalInstanceId,
+    instanceUid: id.instanceUid, identityVersion: 1, environment: c.environment, namespace: id.namespace,
+    releaseId: c.releaseId, leaseId: c.leaseId, leaseExpiresAt: c.leaseExpiresAt, imageDigest, imageRepository: c.imageRepository,
+    deploymentId: c.deploymentId, deploymentTokenSha256: hash(c.deploymentToken),
+    frontendUrl: c.frontendUrl, backendUrl: c.backendUrl, resourceProfile: profile,
+    capabilitiesSha256: hash({ capabilities: c.capabilities || {}, functionalCapabilities: c.functionalCapabilities || {} }) };
+  return { binding, identity: id, receiptName: `oon-preparation-${hash(binding).slice(0, 32)}` };
+}
+
+function pin(doc, name, namespace, kind) {
+  demand(doc?.kind === kind && doc.metadata?.name === name && doc.metadata.namespace === namespace &&
+    UUID.test(doc.metadata.uid || "") && VERSION.test(doc.metadata.resourceVersion || "") &&
+    !doc.metadata.deletionTimestamp, "PREPARED_RUNTIME_RESOURCE_INVALID");
+  return { name, uid: doc.metadata.uid, resourceVersion: doc.metadata.resourceVersion };
+}
+function samePin(doc, expected, namespace, kind) {
+  demand(isDeepStrictEqual(pin(doc, expected?.name, namespace, kind), expected), "PREPARED_RUNTIME_RESOURCE_CHANGED");
+}
+function decodeRuntime(secret) {
+  const values = {};
+  for (const [key, value] of Object.entries(secret.data || {})) {
+    demand(typeof value === "string" && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value), "PREPARED_RUNTIME_SECRET_INVALID");
+    values[key] = Buffer.from(value, "base64").toString("utf8");
+  }
+  return values;
+}
+function assertRuntime(secret, c, id, a) {
+  const env = decodeRuntime(secret);
+  const expected = { NODE_ENV: "production", APP_ENVIRONMENT: c.environment, APP_CODE: c.appCode,
+    PUBLIC_APP_URL: c.frontendUrl, CENTRAL_ATIVACAO_API_URL: a.apiUrl,
+    CENTRAL_ATIVACAO_URL: a.apiUrl.replace(/\/api$/, ""), OON_INSTANCE_UID: id.instanceUid,
+    OON_TECHNICAL_IDENTITY_VERSION: "1", OON_DEPLOYMENT_ID: c.deploymentId,
+    OON_DEPLOYMENT_TOKEN: c.deploymentToken, OON_APP_CODE: c.appCode };
+  demand(Object.entries(expected).every(([k, v]) => env[k] === v) &&
+    typeof env.INSTANCE_CREDENTIAL_ENCRYPTION_KEY === "string" && env.INSTANCE_CREDENTIAL_ENCRYPTION_KEY.length >= 32 &&
+    !["MONGO_ADMIN_URI", "DIGITALOCEAN_TOKEN", "KUBECONFIG", "KUBECONFIG_B64", "PUBLISHER_KUBECONFIG_B64",
+      "GITHUB_APP_PRIVATE_KEY", "GITHUB_CONTROL_PLANE_APP_PRIVATE_KEY"].some(k => Object.hasOwn(env, k)), "PREPARED_RUNTIME_SECRET_INVALID");
+  let uri, username; try { uri = new URL(env.MONGO_URI); username = decodeURIComponent(uri.username); }
+  catch { fail("PREPARED_RUNTIME_MONGO_INVALID"); }
+  demand(["mongodb:", "mongodb+srv:"].includes(uri.protocol) && uri.hostname && uri.password &&
+    username === id.mongoUsername && uri.pathname === `/${id.database}` &&
+    uri.searchParams.get("authSource") === "admin", "PREPARED_RUNTIME_MONGO_INVALID");
+  if (c.functionalCapabilities?.["core.transactional-email"]?.enabled) {
+    let ring; try { ring = JSON.parse(env.OON_TRANSACTIONAL_EMAIL_KEK_KEYRING); } catch { fail("PREPARED_RUNTIME_CAPABILITY_MISSING"); }
+    demand(typeof ring.currentKeyId === "string" && typeof ring.keys?.[ring.currentKeyId] === "string" &&
+      Buffer.from(ring.keys[ring.currentKeyId], "base64").length === 32, "PREPARED_RUNTIME_CAPABILITY_MISSING");
+  }
+  if (c.capabilities?.pdfRendering) {
+    demand(env.OON_CAPABILITY_PDF_RENDERING_URL === c.capabilities.pdfRendering.endpoint &&
+      env.OON_CAPABILITY_PDF_RENDERING_VERSION === c.capabilities.pdfRendering.implementationVersion &&
+      env.OON_CAPABILITY_PDF_RENDERING_USERNAME && env.OON_CAPABILITY_PDF_RENDERING_PASSWORD, "PREPARED_RUNTIME_CAPABILITY_MISSING");
+  }
+}
+
+function kubernetesClient(spawn = spawnSync) {
+  const command = (args, input, code) => {
+    let r; try { r = spawn("kubectl", [...args, "--request-timeout=60s"], {
+      input: input === undefined ? undefined : JSON.stringify(input), encoding: "utf8", timeout: 70000,
+      maxBuffer: 4 * 1024 * 1024, stdio: ["pipe", "pipe", "pipe"],
+    }); } catch { fail(code); }
+    if (r.error || r.status !== 0) fail(code); // Never include provider output or args in diagnostics.
+    return String(r.stdout || "");
+  };
+  const json = (raw, code) => { try { return JSON.parse(raw); } catch { fail(code); } };
+  return {
+    read: (kind, name, namespace) => {
+      const raw = command(["-n", namespace, "get", kind, name, "--ignore-not-found", "-o", "json"], undefined, "PREPARED_RUNTIME_READ_FAILED");
+      return raw.trim() ? json(raw, "PREPARED_RUNTIME_READ_FAILED") : null;
+    },
+    write: (doc, existing) => {
+      let next = copy(doc);
+      if (existing) {
+        next.metadata = { ...existing.metadata, ...next.metadata, resourceVersion: existing.metadata.resourceVersion,
+          uid: existing.metadata.uid, labels: { ...existing.metadata.labels, ...next.metadata.labels },
+          annotations: { ...next.metadata.annotations } };
+        delete next.metadata.managedFields;
+        if (next.kind === "Service") {
+          for (const field of ["clusterIP", "clusterIPs", "ipFamilies", "ipFamilyPolicy", "internalTrafficPolicy"]) {
+            if (existing.spec[field] !== undefined) next.spec[field] = existing.spec[field];
+          }
+        }
+      }
+      // create refuses a concurrent occupant; replace uses resourceVersion CAS.
+      return json(command([existing ? "replace" : "create", "-f", "-", "-o", "json"], next,
+        "PREPARED_RUNTIME_WRITE_OUTCOME_UNKNOWN"), "PREPARED_RUNTIME_WRITE_OUTCOME_UNKNOWN");
+    },
+    rollout: (name, namespace) => command(["-n", namespace, "rollout", "status", `deployment/${name}`, "--timeout=60s"], undefined, "PREPARED_RUNTIME_ROLLOUT_PENDING"),
+  };
+}
+
+function renderPreparedRuntime({ context: c, imageDigest, authority }, receipt) {
+  const { identity: id, binding } = expectedPreparation({ context: c, imageDigest, authority });
+  const [cpuRequest, cpuLimit, memoryRequest, memoryLimit] = PROFILES[binding.resourceProfile];
+  const labels = { "app.kubernetes.io/name": c.appCode, "oon.runtime/instance-uid": id.instanceUid, "oon.runtime/identity-version": "1" };
+  const ownership = { "oon.delivery/installation": authority.installationId, "oon.delivery/authority-uid": authority.instanceUid,
+    "oon.delivery/technical-instance": c.technicalInstanceId, "oon.delivery/environment": c.environment };
+  const metadata = name => ({ name, namespace: id.namespace, labels, annotations: ownership });
+  const ingress = (name, hostname, tlsSecret, route) => ({ apiVersion: "networking.k8s.io/v1", kind: "Ingress",
+    metadata: { ...metadata(name), annotations: { ...ownership, "cert-manager.io/cluster-issuer": receipt.clusterIssuer } },
+    spec: { ingressClassName: receipt.ingressClass, tls: [{ hosts: [hostname], secretName: tlsSecret }],
+      rules: [{ host: hostname, http: { paths: [{ path: route, pathType: "Prefix", backend: { service: { name: c.appCode, port: { name: "http" } } } }] } }] } });
+  return [
+    { apiVersion: "apps/v1", kind: "Deployment", metadata: metadata(c.appCode), spec: {
+      replicas: c.environment === "producao" ? 2 : 1, revisionHistoryLimit: 2,
+      strategy: { type: "RollingUpdate", rollingUpdate: { maxSurge: 1, maxUnavailable: 0 } },
+      selector: { matchLabels: { "app.kubernetes.io/name": c.appCode } },
+      template: { metadata: { labels, annotations: { ...ownership, "oon.delivery/release": c.releaseId,
+        "oon.delivery/lease": c.leaseId, "oon.delivery/image-digest": imageDigest } }, spec: {
+        serviceAccountName: id.serviceAccount, automountServiceAccountToken: false,
+        securityContext: { runAsNonRoot: true, runAsUser: 1000, runAsGroup: 1000, seccompProfile: { type: "RuntimeDefault" } },
+        imagePullSecrets: [{ name: receipt.pullSecret.name }], containers: [{ name: "central", image: `${c.imageRepository}@${imageDigest}`,
+          imagePullPolicy: "IfNotPresent", ports: [{ name: "http", containerPort: 8080 }], envFrom: [{ secretRef: { name: id.secret } }],
+          securityContext: { allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } },
+          resources: { requests: { cpu: cpuRequest, memory: memoryRequest }, limits: { cpu: cpuLimit, memory: memoryLimit } },
+          livenessProbe: { httpGet: { path: "/health/live", port: "http" }, initialDelaySeconds: 20 },
+          readinessProbe: { httpGet: { path: "/api/health/ready", port: "http" }, initialDelaySeconds: 10 } }],
+      } },
+    } },
+    { apiVersion: "v1", kind: "Service", metadata: metadata(c.appCode), spec: { type: "ClusterIP", selector: { "app.kubernetes.io/name": c.appCode }, ports: [{ name: "http", port: 80, targetPort: "http", protocol: "TCP" }] } },
+    ingress(c.appCode, c.frontendHostname, id.tlsSecret, "/"),
+    ingress(`${c.appCode}-api`, c.backendHostname, `${c.appCode}-api-tls`, "/api"),
+  ];
+}
+
+async function deployPreparedRuntime(options, dependencies = {}) {
+  const frozen = copy(options); // No caller mutation while awaiting I/O.
+  const { context: c, authority: a } = frozen;
+  const { binding, identity: id, receiptName } = expectedPreparation(frozen);
+  const kube = dependencies.kube || kubernetesClient();
+  const checkLease = leaseGuard(c.leaseExpiresAt, dependencies);
+  const io = async (operation, ...args) => {
+    checkLease();
+    const result = await kube[operation](...args);
+    checkLease();
+    return result;
+  };
+  const receiptDoc = await io("read", "configmap", receiptName, id.namespace);
+  demand(receiptDoc, "PREPARED_RUNTIME_REQUIRED");
+  const receiptPin = pin(receiptDoc, receiptName, id.namespace, "ConfigMap");
+  let receipt; try { receipt = JSON.parse(receiptDoc.data?.receipt); } catch { fail("PREPARED_RUNTIME_RECEIPT_INVALID"); }
+  demand(receiptDoc.immutable === true && receipt?.phase === "prepared" && isDeepStrictEqual(receipt.binding, binding) &&
+    receipt.ingressClass === "nginx" && receipt.clusterIssuer === "letsencrypt-production-http01" &&
+    receipt.runtimeSecret?.name === id.secret && receipt.runtimeServiceAccount?.name === id.serviceAccount &&
+    receipt.pullSecret?.name === "ghcr-oon", "PREPARED_RUNTIME_RECEIPT_INVALID");
+  const checkPreparation = async () => {
+    samePin(await io("read", "configmap", receiptName, id.namespace), receiptPin, id.namespace, "ConfigMap");
+    const secret = await io("read", "secret", id.secret, id.namespace);
+    samePin(secret, receipt.runtimeSecret, id.namespace, "Secret");
+    assertRuntime(secret, c, id, a);
+    const sa = await io("read", "serviceaccount", id.serviceAccount, id.namespace);
+    samePin(sa, receipt.runtimeServiceAccount, id.namespace, "ServiceAccount");
+    demand(sa.automountServiceAccountToken === false, "PREPARED_RUNTIME_RESOURCE_INVALID");
+    const pull = await io("read", "secret", receipt.pullSecret.name, id.namespace);
+    samePin(pull, receipt.pullSecret, id.namespace, "Secret");
+    demand(pull.type === "kubernetes.io/dockerconfigjson", "PREPARED_RUNTIME_RESOURCE_INVALID");
+  };
+  await checkPreparation();
+  const docs = renderPreparedRuntime(frozen, receipt), existing = [];
+  for (const doc of docs) {
+    const current = await io("read", doc.kind.toLowerCase(), doc.metadata.name, id.namespace);
+    if (current) {
+      pin(current, doc.metadata.name, id.namespace, doc.kind);
+      const ownership = doc.metadata.annotations;
+      demand(Object.entries(ownership).every(([k,v]) => current.metadata.annotations?.[k] === v), "PREPARED_RUNTIME_TARGET_OCCUPIED");
+      // An owned Ingress may still carry routing/auth/snippet directives that
+      // change its behavior. Require explicit reconciliation before any write.
+      demand(isDeepStrictEqual(current.metadata.annotations, ownership), "PREPARED_RUNTIME_ANNOTATIONS_UNAPPROVED");
+    }
+    existing.push(current);
+  }
+  for (let index = 0; index < docs.length; index++) {
+    await checkPreparation();
+    const doc = docs[index], before = existing[index], current = await io("read", doc.kind.toLowerCase(), doc.metadata.name, id.namespace);
+    demand(before ? current?.metadata?.uid === before.metadata.uid && current.metadata.resourceVersion === before.metadata.resourceVersion : current === null,
+      "PREPARED_RUNTIME_TARGET_CHANGED");
+    await io("write", doc, before);
+  }
+  await checkPreparation();
+  await io("rollout", c.appCode, id.namespace);
+  await checkPreparation();
+  checkLease();
+  return { infraVersion: "prepared-member-v2", imageRef: `${c.imageRepository}@${frozen.imageDigest}`,
+    technicalIdentity: id, preparation: { name: receiptName, uid: receiptPin.uid },
+    proofLimits: ["no-distributed-lock-with-administrative-preparation", "rollout-is-not-functional-acceptance"] };
+}
+
+module.exports = { expectedPreparation, renderPreparedRuntime, deployPreparedRuntime, kubernetesClient };

package/src/delivery/preparedRuntime.md

@@ -0,0 +1,132 @@
+# Runtime preparado para membros da plataforma — B5
+
+API opt-in `deployPreparedRuntime({context, imageDigest, authority})`, exportada por
+`delivery/runtime.js`, para `meus-apps`, `oon-workspace` e `oon-docs`. O executor atual
+carrega delivery pelo caminho físico do pacote; nenhum novo subpath npm é exportado.
+O workflow `version-pr` prepara a próxima versão patch; integrar em main aciona
+`release-npm`, que publica os três pacotes após validação. A publicação só deve ser
+registrada como concluída após o run de release. Isso não liga os consumidores
+existentes ao novo adapter.
+
+## Fronteira de confiança
+
+`context` deve vir da Central Prod pelo protocolo autenticado de publicação e lease.
+`authority` é configuração confiável separada, com `installationId`, `instanceUid`
+da raiz e `apiUrl`. Nenhum desses valores pode vir de input livre do workflow.
+O adapter valida consistência; não consulta Mongo, autentica Central nem autoriza
+uma reserva. O consumidor deve validar lease vigente e comando antes de chamá-lo.
+O contexto autenticado precisa incluir `leaseExpiresAt` no formato ISO UTC canônico
+retornado pela Central (`Date.toISOString()`). Ausência, formato inválido ou prazo
+vencido interrompem antes de acessar Kubernetes. Não completar esse campo no
+consumidor com um prazo local nem renovar o lease para reutilizar um recibo.
+
+A preparação administrativa ainda será implementada na Infra. Deve ler novamente
+singleton/configuração bloqueada, comandos e concorrência; conferir identidade,
+release Prod e reservas nativas; preparar somente os alvos aprovados. Durante a
+publicação, deve manter a exclusão mútua e a vigência do lease com a Central. Não
+usar `ensureTechnicalInstance` para descoberta, nem adotar recursos por labels.
+
+O preparador administra Namespace, quota, LimitRange, políticas de rede/admissão,
+ServiceAccount runtime sem token, usuário Mongo limitado ao banco, runtime Secret,
+pull secret e capacidades. Deve preservar recursos/chaves existentes e parar em
+divergência. Nenhuma credencial administrativa deve ser projetada no membro.
+
+## Recibo por publicação
+
+`expectedPreparation(options)` retorna `binding`, `identity` e `receiptName`.
+O binding agora usa `schemaVersion: 2` e inclui `leaseExpiresAt` além de `leaseId`.
+O cálculo é puro e valida o formato, não a vigência no instante de uso; o preparador
+também precisa revalidar a autoridade e o prazo antes de seus próprios efeitos.
+Recibos v1 não são aceitos pelo novo adapter. Não há migração nem adoção automática;
+a futura preparação deve usar a mesma versão do SDK do consumidor. O adapter opt-in
+0.6.12 ainda não está ligado aos consumidores operacionais, portanto este delta não
+altera o provisionador legado nem publica imagens dos membros.
+O preparador deverá usar a mesma função/versão fixada. `receiptName` é
+`oon-preparation-` mais os primeiros 32 hex de SHA256 do JSON canônico de `binding`.
+Objetos são ordenados recursivamente; arrays mantêm ordem. O hash do token também
+usa JSON canônico da string, não os bytes crus. Nunca persistir o token no recibo.
+
+No namespace canônico, criar ConfigMap `immutable: true` com `data.receipt` contendo
+JSON com estes campos:
+
+| Campo | Valor exigido |
+| --- | --- |
+| `phase` | `prepared` |
+| `binding` | Exatamente o retornado pelo SDK v2: autoridade, identidade, ambiente, release, lease e vencimento, imagem/digest, deployment, URLs, perfil e hashes das capacidades/token |
+| `ingressClass` | `nginx` |
+| `clusterIssuer` | `letsencrypt-production-http01` |
+| `runtimeSecret` | `{name, uid, resourceVersion}` do Secret canônico final |
+| `runtimeServiceAccount` | `{name, uid, resourceVersion}` da SA canônica final |
+| `pullSecret` | `{name: "ghcr-oon", uid, resourceVersion}` do Secret local final |
+
+O recibo é o último recurso da preparação. Não é uma assinatura: sua autoridade
+depende de o executor não poder criar/alterar/apagar ConfigMaps, Secrets ou SAs.
+Não reutilizar recibo em outro lease/digest. UID e resourceVersion dos recursos são
+reconferidos antes de cada escrita e após o rollout. Isso detecta deriva observada,
+mas não substitui um lock distribuído com o preparador.
+
+`deployPreparedRuntime` confere o prazo antes e depois de cada leitura, escrita e
+rollout, além de antes do retorno de sucesso (`infraVersion: prepared-member-v2`).
+O orçamento inicial de tempo também é acompanhado por relógio monotônico: um recuo
+do relógio civil durante a chamada não prolonga o prazo. Observação inválida do
+relógio interrompe. O relógio civil inicial do executor precisa estar sincronizado;
+essa checagem local não consulta revogação, comando ou lease na Central.
+
+Expiração durante uma requisição não cancela um efeito que já chegou ao servidor.
+O erro `PREPARED_RUNTIME_LEASE_EXPIRED` pode corresponder a escrita parcial; preservar
+e reconciliar os recursos com o comando, sem retry automático, rollback, remoção de
+lock ou takeover. Um novo processo não deve reusar o mesmo lease como autorização
+de concorrência. Exclusão administrativa, fencing/admissão e frescor de callbacks
+permanecem requisitos separados de B5.
+
+O runtime Secret deve conter identidade/URLs, credencial de deployment e chave de
+criptografia já preparadas. Mongo exige URI de host único `mongodb`/`mongodb+srv`,
+usuário e banco canônicos e `authSource=admin`; o adapter não prova os privilégios
+desse usuário. E-mail habilitado exige keyring existente; PDF exige endpoint,
+versão e credenciais projetadas. O adapter nunca gera chaves ou busca Secrets
+administrativos. A recusa de nomes administrativos conhecidos é defesa adicional,
+não uma prova da origem ou do escopo de todas as credenciais.
+
+## Permissões necessárias e limites
+
+Leitura `get` somente dos nomes do recibo, runtime Secret, pull Secret e runtime SA
+no alvo; leitura/escrita de Deployment, Service e dois Ingresses canônicos; rollout
+consulta/observa o Deployment nomeado. Não requer namespaces, RBAC, nodes, jobs,
+pods/exec, serviceaccounts/token ou acesso a `oon-system`/outros namespaces.
+
+Não aplicar uma Role genérica com base apenas nesta lista. `create` de recursos
+principais não pode ser limitado por `resourceNames` no RBAC; workloads também
+podem montar Secrets e escolher SAs. Antes de conceder escrita, a Infra deve
+implementar e provar admissão restritiva (nomes, imagem, hosts, SAs, referências a
+Secrets, pod security) ou um mecanismo administrativo equivalente. RBAC deve ser
+por alvo/ambiente/instalação, com autenticação dedicada e recusas cruzadas. Ver
+[limites oficiais do RBAC](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#referring-to-resources).
+
+O renderer produz somente Deployment, Service e Ingresses frontend/backend, por
+digest, sem token de SA, sem privilégio, UID/GID 1000 e seccomp RuntimeDefault.
+A compatibilidade das imagens dos três membros com esse usuário ainda precisa
+ser provada. Não oferece manifest arbitrário, initContainers, volumes ou hooks.
+
+Um alvo existente exige ownership correspondente e UID/resourceVersion observados;
+annotations adicionais são recusadas antes de qualquer escrita, inclusive regras
+de rewrite, redirect, autenticação ou snippets de Ingress. Exigem reconciliação
+administrativa explícita; não são herdadas silenciosamente na substituição.
+`replace` usa CAS, `create` recusa ocupante concorrente. Essa conferência no cliente
+não é autorização nem prova de ownership canônico no banco. Não adota recursos
+legados. Falha parcial/resultado de escrita incerto interrompe sem retry ou rollback.
+O operador deve reconciliar resultado com o comando antes de tentar novamente.
+Rollout tem limite de 60 segundos; timeout é pendência, não motivo para nova escrita.
+Rollout bem-sucedido não prova HTTP, TLS, callback ou aceite funcional.
+
+## Gate de uso
+
+Manter delivery bloqueado até implementar preparador e admissão/bindings, provar
+positivos e recusas por alvo, publicar a versão do SDK e ligar ambos os consumidores
+ao novo adapter. O preparador de kubeconfig atual exige `create namespaces` e o
+script atual ainda chama provisionamento administrativo: ambos precisam de caminho
+específico para membros. Não satisfazer esse guard concedendo namespace create.
+Nenhuma chamada deve cair no provisionador antigo se o recibo estiver ausente.
+
+Testes locais: `node --test packages/oonCore-back/test/prepared-runtime.test.js
+packages/oonCore-back/test/delivery-technical-identity.test.js`. Os fakes verificam
+comportamento do adapter; não comprovam permissões Kubernetes ou integração real.

package/src/delivery/runtime.js

@@ -363,6 +363,8 @@ module.exports = {
   runtimeManifest,
   provisionRuntime,
   deployRuntime,
+  // Explicit opt-in for a separately prepared target; never a provisioning fallback.
+  deployPreparedRuntime: require("./preparedRuntime").deployPreparedRuntime,
   waitHttp,
   activateMember,
 };