@oondemand/oon-core-back 0.6.12 → 0.6.13

package/package.json

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

package/src/delivery/preparedRuntime.js

@@ -4,6 +4,7 @@
 // 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"]);
@@ -27,6 +28,30 @@ function stable(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 }) {
@@ -40,6 +65,7 @@ function expectedPreparation({ context: c, imageDigest, authority: a }) {
     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`;
@@ -48,10 +74,10 @@ function expectedPreparation({ context: c, imageDigest, authority: a }) {
     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: 1, installationId: a.installationId, authorityInstanceUid: a.instanceUid,
+  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, imageDigest, imageRepository: c.imageRepository,
+    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 || {} }) };
@@ -178,7 +204,14 @@ async function deployPreparedRuntime(options, dependencies = {}) {
   const { context: c, authority: a } = frozen;
   const { binding, identity: id, receiptName } = expectedPreparation(frozen);
   const kube = dependencies.kube || kubernetesClient();
-  const receiptDoc = await kube.read("configmap", receiptName, id.namespace);
+  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"); }
@@ -187,21 +220,21 @@ async function deployPreparedRuntime(options, dependencies = {}) {
     receipt.runtimeSecret?.name === id.secret && receipt.runtimeServiceAccount?.name === id.serviceAccount &&
     receipt.pullSecret?.name === "ghcr-oon", "PREPARED_RUNTIME_RECEIPT_INVALID");
   const checkPreparation = async () => {
-    samePin(await kube.read("configmap", receiptName, id.namespace), receiptPin, id.namespace, "ConfigMap");
-    const secret = await kube.read("secret", id.secret, id.namespace);
+    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 kube.read("serviceaccount", id.serviceAccount, id.namespace);
+    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 kube.read("secret", receipt.pullSecret.name, id.namespace);
+    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 kube.read(doc.kind.toLowerCase(), doc.metadata.name, id.namespace);
+    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;
@@ -214,15 +247,16 @@ async function deployPreparedRuntime(options, dependencies = {}) {
   }
   for (let index = 0; index < docs.length; index++) {
     await checkPreparation();
-    const doc = docs[index], before = existing[index], current = await kube.read(doc.kind.toLowerCase(), doc.metadata.name, id.namespace);
+    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 kube.write(doc, before);
+    await io("write", doc, before);
   }
   await checkPreparation();
-  await kube.rollout(c.appCode, id.namespace);
+  await io("rollout", c.appCode, id.namespace);
   await checkPreparation();
-  return { infraVersion: "prepared-member-v1", imageRef: `${c.imageRepository}@${frozen.imageDigest}`,
+  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"] };
 }

package/src/delivery/preparedRuntime.md

@@ -3,7 +3,7 @@
 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 versão 0.6.12; integrar em main aciona
+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.
@@ -15,6 +15,10 @@ existentes ao novo adapter.
 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,
@@ -30,6 +34,13 @@ 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
@@ -41,7 +52,7 @@ JSON com estes campos:
 | Campo | Valor exigido |
 | --- | --- |
 | `phase` | `prepared` |
-| `binding` | Exatamente o retornado pelo SDK: autoridade, identidade, ambiente, release, lease, imagem/digest, deployment, URLs, perfil e hashes das capacidades/token |
+| `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 |
@@ -54,6 +65,20 @@ Não reutilizar recibo em outro lease/digest. UID e resourceVersion dos recursos
 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