@orangecheck/agent-core 1.0.1 → 1.2.0

package/dist/index.mjs

@@ -944,7 +944,194 @@ function isHex64(s) {
 function isIsoUtc(s) {
   return typeof s === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(s);
 }
+function federationDescriptorCanonicalMessage(descriptor) {
+  const addresses = descriptor.guardians.map((g) => g.address).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  return [
+    "oc-agent:federation:v1",
+    `threshold: ${descriptor.threshold}`,
+    ...addresses.map((a) => `guardian: ${a}`)
+  ].join("\n");
+}
+function computeFederationDescriptorId(descriptor) {
+  return hexEncode(sha256(new TextEncoder().encode(federationDescriptorCanonicalMessage(descriptor))));
+}
+function parseThreshold(t) {
+  if (typeof t !== "string") return null;
+  const m = /^(\d+)-of-(\d+)$/.exec(t);
+  if (!m) return null;
+  const mm = Number(m[1]);
+  const nn = Number(m[2]);
+  if (!Number.isInteger(mm) || !Number.isInteger(nn) || mm < 1 || mm > nn) return null;
+  return { m: mm, n: nn };
+}
+var HEX64 = /^[0-9a-f]{64}$/;
+var ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+async function checkFederationQuorum(principal, sig, reconstructedId, input) {
+  if (principal?.alg !== "federation") {
+    return fail("E_MALFORMED", 'principal.alg must be "federation"');
+  }
+  const descriptor = principal.descriptor;
+  if (!descriptor || descriptor.kind !== "agent-federation") {
+    return fail("E_MALFORMED", "principal.descriptor missing or wrong kind");
+  }
+  const parsed = parseThreshold(descriptor.threshold);
+  if (!parsed) return fail("E_MALFORMED", `malformed threshold "${descriptor.threshold}"`);
+  if (!Array.isArray(descriptor.guardians) || descriptor.guardians.length !== parsed.n) {
+    return fail("E_MALFORMED", "guardians length must equal N in M-of-N");
+  }
+  const computedDescId = computeFederationDescriptorId(descriptor);
+  if (principal.descriptor_id !== computedDescId) {
+    return fail(
+      "E_BAD_FEDERATION_DESCRIPTOR",
+      `declared descriptor_id (${principal.descriptor_id}) != canonical hash (${computedDescId})`
+    );
+  }
+  if (sig?.alg !== "federation-bip322") {
+    return fail("E_MALFORMED", 'sig.alg must be "federation-bip322"');
+  }
+  if (sig.threshold !== descriptor.threshold) {
+    return fail(
+      "E_THRESHOLD_MISMATCH",
+      `sig.threshold (${sig.threshold}) != descriptor.threshold (${descriptor.threshold})`
+    );
+  }
+  const sigs = sig.signatures;
+  if (!Array.isArray(sigs)) return fail("E_MALFORMED", "sig.signatures must be an array");
+  if (sigs.length < parsed.m) {
+    return fail(
+      "E_THRESHOLD_NOT_MET",
+      `${sigs.length} signature(s) below threshold M=${parsed.m}`
+    );
+  }
+  const guardianSet = new Set(descriptor.guardians.map((g) => g.address));
+  const seen = /* @__PURE__ */ new Set();
+  for (const s of sigs) {
+    if (!guardianSet.has(s.guardian_address)) {
+      return fail("E_UNKNOWN_GUARDIAN", `${s.guardian_address} is not a declared guardian`);
+    }
+    if (seen.has(s.guardian_address)) {
+      return fail("E_DUPLICATE_GUARDIAN", `${s.guardian_address} signed more than once`);
+    }
+    seen.add(s.guardian_address);
+  }
+  if (!input.skipSignatureVerification) {
+    if (!input.verifyBip322) return fail("E_BAD_SIG", "no BIP-322 verifier supplied");
+    for (const s of sigs) {
+      const ok = await input.verifyBip322(reconstructedId, s.value, s.guardian_address);
+      if (!ok) {
+        return fail("E_BAD_SIG", `guardian ${s.guardian_address} signature did not verify`);
+      }
+    }
+  }
+  return { ok: true };
+}
+async function verifyFederationDelegation(input) {
+  const env = input.envelope;
+  if (env?.kind !== "agent-delegation") return fail("E_MALFORMED", 'kind must be "agent-delegation"');
+  if (!HEX64.test(env.id ?? "")) return fail("E_MALFORMED", "id must be 64 lowercase hex chars");
+  if (!env.agent?.address || env.agent.alg !== "bip322") return fail("E_MALFORMED", "agent invalid");
+  if (!Array.isArray(env.scopes) || env.scopes.length === 0) {
+    return fail("E_MALFORMED", "scopes must be a non-empty array");
+  }
+  if (!ISO_UTC.test(env.issued_at) || !ISO_UTC.test(env.expires_at)) {
+    return fail("E_MALFORMED", "issued_at / expires_at must be ISO 8601 UTC");
+  }
+  if (!/^[0-9a-f]{32}$/.test(env.nonce)) return fail("E_MALFORMED", "nonce must be 32 hex chars");
+  let canonicalScopes;
+  try {
+    canonicalScopes = canonicalizeScopes(env.scopes);
+  } catch (e) {
+    return fail("E_BAD_SCOPE_GRAMMAR", e.message);
+  }
+  for (let i = 0; i < canonicalScopes.length; i++) {
+    if (env.scopes[i] !== canonicalScopes[i]) {
+      return fail("E_BAD_SCOPE_GRAMMAR", `scope index ${i} not in canonical order`);
+    }
+  }
+  const canonInput = {
+    principal: `federation:${env.principal?.descriptor_id ?? ""}`,
+    agent: env.agent.address,
+    scopes: canonicalScopes,
+    bond_sats: env.bond?.sats ?? 0,
+    bond_attestation: env.bond?.attestation_id ?? "none",
+    issued_at: env.issued_at,
+    expires_at: env.expires_at,
+    nonce: env.nonce
+  };
+  const reconstructedId = computeDelegationId(canonInput);
+  if (reconstructedId !== env.id) {
+    return fail("E_BAD_ID", `reconstructed id (${reconstructedId}) != envelope.id (${env.id})`);
+  }
+  const quorum = await checkFederationQuorum(env.principal, env.sig, env.id, input);
+  if (!quorum.ok) return quorum;
+  if (!input.skipTemporalCheck) {
+    const now = input.now ?? /* @__PURE__ */ new Date();
+    const issued = new Date(env.issued_at);
+    const expires = new Date(env.expires_at);
+    if (expires <= issued) return fail("E_MALFORMED", "expires_at <= issued_at");
+    if (now < issued) return fail("E_NOT_YET_VALID", `delegation not valid until ${env.issued_at}`);
+    if (now >= expires) return fail("E_EXPIRED", `delegation expired at ${env.expires_at}`);
+  }
+  return { ok: true, id: env.id, canonicalMessage: delegationCanonicalMessage(canonInput) };
+}
+async function verifyFederationRevocation(input) {
+  const env = input.envelope;
+  if (env?.kind !== "agent-revocation") return fail("E_MALFORMED", 'kind must be "agent-revocation"');
+  if (!HEX64.test(env.id ?? "")) return fail("E_MALFORMED", "id must be 64 lowercase hex chars");
+  if (!HEX64.test(env.delegation_id ?? "")) return fail("E_MALFORMED", "delegation_id must be 64-hex");
+  if (typeof env.reason !== "string" || env.reason.length > 128) {
+    return fail("E_MALFORMED", "reason must be a string \u2264128 bytes");
+  }
+  if (!ISO_UTC.test(env.signed_at)) return fail("E_MALFORMED", "signed_at must be ISO 8601 UTC");
+  const canonInput = {
+    address: `federation:${env.signer?.descriptor_id ?? ""}`,
+    delegation_id: env.delegation_id,
+    reason: env.reason,
+    signed_at: env.signed_at
+  };
+  const reconstructedId = computeRevocationId(canonInput);
+  if (reconstructedId !== env.id) {
+    return fail("E_BAD_ID", `reconstructed id (${reconstructedId}) != envelope.id (${env.id})`);
+  }
+  const quorum = await checkFederationQuorum(env.signer, env.sig, env.id, input);
+  if (!quorum.ok) return quorum;
+  return { ok: true, id: env.id, canonicalMessage: revocationCanonicalMessage(canonInput) };
+}
+function fail(code, message) {
+  return { ok: false, code, message };
+}
+
+// src/assert-scope.ts
+var ScopeNotGrantedError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.name = "ScopeNotGrantedError";
+    this.reason = reason;
+  }
+};
+function assertScopeGranted(delegation, scopeExercised, fnName) {
+  if (hasPrivateScopes(delegation)) {
+    throw new ScopeNotGrantedError(
+      "scopes_encrypted",
+      `${fnName}: this delegation uses v1.2 private scopes \u2014 \`scopes_encrypted\` is set and \`scopes\` is absent, so the granted set cannot be read here. Decrypt it with decryptPrivateScopes() using a matching device key and pass the recovered scopes as \`delegation.scopes\`. Refusing to stamp \`${scopeExercised}\` against an unreadable grant.`
+    );
+  }
+  const scopes = delegation.scopes;
+  if (scopes === void 0 || scopes.length === 0) {
+    throw new ScopeNotGrantedError(
+      "no_scopes",
+      `${fnName}: delegation grants no scopes, so \`${scopeExercised}\` cannot be exercised. An absent or empty \`scopes\` means nothing is granted, never everything.`
+    );
+  }
+  const exercised = parseScope(scopeExercised);
+  if (!scopes.map(parseScope).some((g) => isSubScope(exercised, g))) {
+    throw new ScopeNotGrantedError(
+      "not_subscope",
+      `${fnName}: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope (${scopes.join(", ")})`
+    );
+  }
+}
 
-export { AgentError, DEFAULT_MAX_CHAIN_DEPTH, ENVELOPE_VERSION, REGISTERED_SCOPES, ScopeParseError, actionCanonicalBytes, actionCanonicalMessage, canonicalActionBytes, canonicalDelegationBytes, canonicalRevocationBytes, canonicalizeAction, canonicalizeDelegation, canonicalizeRevocation, canonicalizeScope, canonicalizeScopeString, canonicalizeScopes, computeActionId, computeDelegationId, computeRevocationId, computeSubdelegationId, decodeScopesPayload, delegationCanonicalBytes, delegationCanonicalMessage, encodeScopesPayload, hasPrivateScopes, isSubScope, parseAndCanonicalizeScopes, parseScope, revocationCanonicalBytes, revocationCanonicalMessage, sealScopes, sha256Hex, subdelegationCanonicalBytes, subdelegationCanonicalMessage, unsealScopes, validateScope, verifyAction, verifyDelegation, verifyRevocation, verifySubdelegation };
+export { AgentError, DEFAULT_MAX_CHAIN_DEPTH, ENVELOPE_VERSION, REGISTERED_SCOPES, ScopeNotGrantedError, ScopeParseError, actionCanonicalBytes, actionCanonicalMessage, assertScopeGranted, canonicalActionBytes, canonicalDelegationBytes, canonicalRevocationBytes, canonicalizeAction, canonicalizeDelegation, canonicalizeRevocation, canonicalizeScope, canonicalizeScopeString, canonicalizeScopes, computeActionId, computeDelegationId, computeFederationDescriptorId, computeRevocationId, computeSubdelegationId, decodeScopesPayload, delegationCanonicalBytes, delegationCanonicalMessage, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, isSubScope, parseAndCanonicalizeScopes, parseScope, revocationCanonicalBytes, revocationCanonicalMessage, sealScopes, sha256Hex, subdelegationCanonicalBytes, subdelegationCanonicalMessage, unsealScopes, validateScope, verifyAction, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map