@saulwade/swl-ses 2.6.1 → 2.8.0

package/scripts/lib/principal-verifier.js

@@ -0,0 +1,178 @@
+'use strict';
+
+/** Verifica atestaciones de identidad y emite principals opacos. */
+
+const crypto = require('node:crypto');
+
+const {
+  exactKeys, fail, freezeDeep, getContractValidators, plainObject,
+} = require('./policy-verifier-utils');
+const signed = require('./signed-envelope');
+
+const PRINCIPALS = new WeakSet();
+const PRINCIPAL_META = new WeakMap();
+const SHA256 = /^[a-f0-9]{64}$/u;
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const AGENT = /^agent:[a-f0-9]{64}$/u;
+const SKILL = /^skill:[a-f0-9]{64}$/u;
+const CLAIM_KEYS = [
+  'kind', 'schemaVersion', 'principalId', 'agentNodeId', 'delegationChain',
+  'sessionId', 'runtimeId', 'projectId', 'worktreeDigest', 'operationDigest',
+  'issuedAt', 'expiresAt', 'nonce',
+];
+const OPTION_KEYS = ['trustContext', 'dependencies', 'operation'];
+
+function sortedUnique(values, pattern) {
+  return Array.isArray(values)
+    && values.every((value) => typeof value === 'string' && pattern.test(value))
+    && values.every((value, index) => index === 0 || values[index - 1] < value);
+}
+
+function validateDelegationEntry(entry) {
+  plainObject(entry, 'PRINCIPAL_INVALID', 'delegación');
+  exactKeys(
+    entry, ['agentNodeId', 'allowedCapabilities', 'allowedSkillNodeIds'],
+    'PRINCIPAL_INVALID', 'delegación'
+  );
+  if (!AGENT.test(entry.agentNodeId)
+      || !sortedUnique(entry.allowedCapabilities, IDENTIFIER)
+      || !sortedUnique(entry.allowedSkillNodeIds, SKILL)) {
+    fail('PRINCIPAL_INVALID', 'delegación inválida');
+  }
+}
+
+function isSubset(values, parent) {
+  const allowed = new Set(parent);
+  return values.every((value) => allowed.has(value));
+}
+
+function validateDelegation(chain, agentNodeId) {
+  if (!Array.isArray(chain) || chain.length === 0 || chain.length > 16) {
+    fail('PRINCIPAL_INVALID', 'cadena de delegación inválida');
+  }
+  chain.forEach(validateDelegationEntry);
+  if (new Set(chain.map((item) => item.agentNodeId)).size !== chain.length
+      || chain.at(-1).agentNodeId !== agentNodeId) {
+    fail('PRINCIPAL_INVALID', 'cadena de delegación cíclica o inconsistente');
+  }
+  for (let index = 1; index < chain.length; index += 1) {
+    const parent = chain[index - 1];
+    const child = chain[index];
+    if (!isSubset(child.allowedCapabilities, parent.allowedCapabilities)
+        || !isSubset(child.allowedSkillNodeIds, parent.allowedSkillNodeIds)) {
+      fail('PRINCIPAL_INVALID', 'delegación amplía permisos');
+    }
+  }
+}
+
+function validateClaims(claims, operation, now) {
+  plainObject(claims, 'PRINCIPAL_INVALID', 'claims principal');
+  exactKeys(claims, CLAIM_KEYS, 'PRINCIPAL_INVALID', 'claims principal');
+  if (claims.kind !== 'principal-attestation' || claims.schemaVersion !== '1.0.0') {
+    fail('PRINCIPAL_INVALID', 'principal futuro o inválido');
+  }
+  for (const field of ['principalId', 'sessionId', 'runtimeId', 'projectId', 'nonce']) {
+    if (!IDENTIFIER.test(claims[field])) fail('PRINCIPAL_INVALID', `${field} inválido`);
+  }
+  if (!AGENT.test(claims.agentNodeId) || !SHA256.test(claims.worktreeDigest)
+      || claims.operationDigest !== operation.operationDigest) {
+    fail('PRINCIPAL_BINDING_INVALID', 'binding del principal inválido');
+  }
+  validateDelegation(claims.delegationChain, claims.agentNodeId);
+  signed.validarTimestampIso(claims.issuedAt, 'principal issuedAt');
+  signed.validarTimestampIso(claims.expiresAt, 'principal expiresAt');
+  if (claims.issuedAt > now || claims.expiresAt < now || claims.issuedAt >= claims.expiresAt) {
+    fail('PRINCIPAL_EXPIRED', 'principal fuera de vigencia');
+  }
+}
+
+function validateOptions(options) {
+  plainObject(options, 'PRINCIPAL_OPTIONS_INVALID', 'opciones principal');
+  exactKeys(options, OPTION_KEYS, 'PRINCIPAL_OPTIONS_INVALID', 'opciones principal');
+  const contract = getContractValidators();
+  if (!contract.isKernelDependencies(options.dependencies)) {
+    fail('PRINCIPAL_OPTIONS_INVALID', 'dependencies no verificadas');
+  }
+  if (!contract.isVerifiedOperation(options.operation)) {
+    fail('PRINCIPAL_OPTIONS_INVALID', 'operación no verificada');
+  }
+}
+
+function assertAuthority(envelope, authority) {
+  if (envelope.trustEpoch !== authority.trustEpoch
+      || envelope.trustDigest !== authority.trustDigest
+      || envelope.rootKeyDigest !== authority.rootKeyDigest) {
+    fail('PRINCIPAL_TRUST_INVALID', 'principal ligado a trust distinto');
+  }
+}
+
+function createPrincipal(envelope, operation, integrityLedger, authority) {
+  const digestInput = {
+    issuer: envelope.issuer, subject: envelope.subject,
+    trustEpoch: envelope.trustEpoch, trustDigest: envelope.trustDigest,
+    claims: envelope.claims,
+  };
+  const principalDigest = crypto.createHash('sha256')
+    .update(signed.canonicalizarIJson(digestInput), 'utf8').digest('hex');
+  const principal = freezeDeep({
+    kind: 'verified-principal', ...structuredClone(envelope.claims),
+    issuer: envelope.issuer, subject: envelope.subject,
+    keyId: envelope.keyId, rootKeyDigest: envelope.rootKeyDigest,
+    signerPublicKeyDigest: envelope.signerPublicKeyDigest,
+    verifiedScope: envelope.verifiedScope,
+    trustEpoch: envelope.trustEpoch, trustDigest: envelope.trustDigest,
+    operationDigest: operation.operationDigest, principalDigest,
+  });
+  PRINCIPALS.add(principal);
+  PRINCIPAL_META.set(principal, Object.freeze({
+    envelope, integrityLedger, streamId: authority.streamId,
+  }));
+  return principal;
+}
+
+function assertPrincipalCurrent(principal, authority) {
+  if (!PRINCIPALS.has(principal)) fail('PRINCIPAL_INVALID', 'principal no verificado');
+  const metadata = PRINCIPAL_META.get(principal);
+  if (!metadata.integrityLedger.isAuthorityReceipt(authority)
+      || authority.streamId !== metadata.streamId
+      || authority.rootKeyDigest !== principal.rootKeyDigest
+      || typeof authority.observedAt !== 'string') {
+    fail('PRINCIPAL_AUTHORITY_INVALID', 'autoridad no verificada');
+  }
+  const current = signed.revalidarEnvelopeVerificado(metadata.envelope, authority.observedAt);
+  if (current.trustEpoch !== authority.trustEpoch
+      || current.trustDigest !== authority.trustDigest
+      || current.rootKeyDigest !== authority.rootKeyDigest) {
+    fail('PRINCIPAL_TRUST_INVALID', 'principal ligado a trust obsoleto');
+  }
+  if (principal.issuedAt > authority.observedAt || principal.expiresAt < authority.observedAt) {
+    fail('PRINCIPAL_EXPIRED', 'principal fuera de vigencia');
+  }
+  return true;
+}
+
+function verifyPrincipal(rawBytes, options) {
+  validateOptions(options);
+  const authority = options.dependencies.integrityLedger.readAuthority();
+  const envelope = signed.verificarEnvelope(rawBytes, {
+    trustContext: options.trustContext,
+    expectedType: 'principal',
+    requiredScope: `principal:${options.operation.capability}`,
+    now: authority.observedAt,
+  });
+  assertAuthority(envelope, authority);
+  validateClaims(envelope.claims, options.operation, authority.observedAt);
+  return createPrincipal(
+    envelope, options.operation, options.dependencies.integrityLedger, authority
+  );
+}
+
+function isVerifiedPrincipal(value) {
+  return PRINCIPALS.has(value);
+}
+
+module.exports = {
+  assertPrincipalCurrent,
+  isVerifiedPrincipal,
+  verifyPrincipal,
+};