xytara 2.2.0 → 2.4.0

package/RELEASE_NOTES.md

@@ -1,17 +1,18 @@
-# xytara 2.2.0 Release Notes
+# xytara 2.4.0 Release Notes
 
-`xytara` 2.2.0 is the public machine-commerce program-complete line.
+`xytara` 2.4.0 is the foundation-convergence line for runtime wallet, authority, identity, trust, registry, and participation.
 
 Highlights:
 
 - direct one-line machine execution with `xytara-run`
-- release, comparison, adoption, scenario, and launch packs over HTTP and CLI
-- release-center, announcement-pack, and release-candidate surfaces for public launch readiness
-- credits-first reusable spend posture
-- native settlement-aware runtime inspection
-- proof-compatible handoff into `xoonya`
-- partner-ready onboarding and launch docs
-- explicit runtime durability posture, including Supabase-backed persistence on hosts without persistent disk
+- first-class wallet / ledger / lifecycle / reserve / commit / reversal inspection
+- first-class authority bindings with scoped and bounded contract enforcement
+- first-class machine-identity bindings, review, rotation, and operator bundle surfaces
+- explicit capability-registry, pricing-policy, quote-policy, trust-input, and trust-layer packages
+- multi-operator and external network participation packages with bounded admission flows
+- credits-first reusable spend posture with durable runtime economics state
+- native settlement-aware runtime inspection and proof-compatible handoff into `xoonya`
+- partner-ready onboarding, launch docs, and public example paths remain in place
 
 Recommended first checks:
 
@@ -19,10 +20,15 @@ Recommended first checks:
 2. `xytara-release --candidate --summary`
 3. `npm run verify:release-candidate`
 4. `node examples/partner_launch_walkthrough.js`
-5. inspect `/v1/release-candidate/summary` and `/v1/runtime/durability` on the deployed service
+5. inspect `/v1/economics/accounts/:account_id/wallet-ledger-bundle`
+6. inspect `/v1/economics/accounts/:account_id/authority-bundle`
+7. inspect `/v1/economics/accounts/:account_id/machine-identity-operator-bundle`
+8. inspect `/v1/capability-registry/package`
+9. inspect `/v1/economics/accounts/:account_id/network-participation-package`
 
 Recommended first docs:
 
 - `PROGRAM_COMPLETE_RELEASE.md`
+- `FINAL_CONTRACT.md`
 - `WHY_XYTARA_XOONYA.md`
 - `PARTNER_READY_PATH.md`

package/lib/account_auth.js

@@ -44,6 +44,84 @@ function buildCredentialPublicView(credential, includeToken = false) {
   return view;
 }
 
+function buildAuthorityBindingPublicView(binding, credential, includeToken = false) {
+  if (!binding) return null;
+  const view = {
+    binding_id: binding.binding_id,
+    account_id: binding.account_id,
+    status: binding.status,
+    authority_kind: binding.authority_kind,
+    spend_posture: binding.spend_posture,
+    scope: binding.scope,
+    authority_scope: ensureArray(binding.authority_scope),
+    allowed_consequence_families: ensureArray(binding.allowed_consequence_families),
+    consequence_bounds: binding.consequence_bounds || {
+      max_commit_units: null,
+      max_reserve_units: null,
+      max_reversal_units: null
+    },
+    agent_id: binding.agent_id,
+    budget_id: binding.budget_id,
+    pack_id: binding.pack_id || null,
+    entitlement_id: binding.entitlement_id || null,
+    credential_id: binding.credential_id || null,
+    issued_by: binding.issued_by || null,
+    labels: ensureArray(binding.labels),
+    expires_at_iso: binding.expires_at_iso || null,
+    rotated_from_binding_id: binding.rotated_from_binding_id || null,
+    replaced_by_binding_id: binding.replaced_by_binding_id || null,
+    created_at_iso: binding.created_at_iso,
+    updated_at_iso: binding.updated_at_iso,
+    revoked_at_iso: binding.revoked_at_iso || null,
+    revoke_reason: binding.revoke_reason || null,
+    spend_credential: buildCredentialPublicView(credential, includeToken)
+  };
+  return view;
+}
+
+function buildAuthorityBindingContractSummary(binding, credential) {
+  if (!binding) return null;
+  const publicView = buildAuthorityBindingPublicView(binding, credential, false);
+  return {
+    summary_version: "xytara-authority-binding-contract-summary-v1",
+    binding_id: binding.binding_id,
+    account_id: binding.account_id,
+    authority_kind: binding.authority_kind,
+    spend_posture: binding.spend_posture,
+    authority_scope: ensureArray(binding.authority_scope),
+    allowed_consequence_families: ensureArray(binding.allowed_consequence_families),
+    consequence_bounds: publicView.consequence_bounds,
+    linked_credential_id: binding.credential_id || null,
+    contract_state: binding.status === "active" ? "active_contract" : "inactive_contract",
+    linked_surfaces: {
+      binding_ref: `/v1/account-auth/authority-bindings/${encodeURIComponent(binding.binding_id)}`,
+      spend_credential_ref: binding.credential_id ? `/v1/account-auth/spend-credentials/${encodeURIComponent(binding.credential_id)}` : null
+    }
+  };
+}
+
+function buildAuthorityBindingRotationSummary(binding, credential) {
+  if (!binding) return null;
+  const active = binding.status === "active";
+  return {
+    summary_version: "xytara-authority-binding-rotation-summary-v1",
+    binding_id: binding.binding_id,
+    account_id: binding.account_id,
+    status: binding.status,
+    renewable_state: active ? "renewable" : "inactive",
+    rotatable_state: active ? "rotatable" : "inactive",
+    expires_at_iso: binding.expires_at_iso || null,
+    rotated_from_binding_id: binding.rotated_from_binding_id || null,
+    replaced_by_binding_id: binding.replaced_by_binding_id || null,
+    linked_credential_id: binding.credential_id || null,
+    linked_surfaces: {
+      binding_ref: `/v1/account-auth/authority-bindings/${encodeURIComponent(binding.binding_id)}`,
+      contract_summary_ref: `/v1/account-auth/authority-bindings/${encodeURIComponent(binding.binding_id)}/contract-summary`,
+      spend_credential_ref: binding.credential_id ? `/v1/account-auth/spend-credentials/${encodeURIComponent(binding.credential_id)}` : null
+    }
+  };
+}
+
 function isCredentialExpired(credential) {
   if (!credential || !credential.expires_at_iso) return false;
   const expiresAt = Date.parse(credential.expires_at_iso);
@@ -84,6 +162,57 @@ function createSpendCredential(state, body) {
   return buildCredentialPublicView(credential, true);
 }
 
+function createAuthorityBinding(state, body) {
+  const payload = ensureObject(body);
+  const bindingId = normalizeString(payload.binding_id, `authority_binding_${state.accountAuthorityBindings.size + 1}`);
+  const credential = createSpendCredential(state, {
+    credential_id: normalizeString(payload.credential_id, `spend_for_${bindingId}`),
+    bearer_token: normalizeString(payload.bearer_token, null),
+    account_id: normalizeString(payload.account_id, "acct_demo"),
+    agent_id: normalizeString(payload.agent_id, null),
+    budget_id: normalizeString(payload.budget_id, null),
+    pack_id: normalizeString(payload.pack_id, null),
+    entitlement_id: normalizeString(payload.entitlement_id, null),
+    scope: normalizeString(payload.scope, "runtime_spend"),
+    labels: ensureArray(payload.labels),
+    status: normalizeString(payload.status, "active"),
+    issued_by: normalizeString(payload.issued_by, "operator"),
+    expires_at_iso: normalizeString(payload.expires_at_iso, null)
+  });
+  const createdAtIso = nowIso();
+  const binding = {
+    binding_id: bindingId,
+    account_id: credential.account_id,
+    credential_id: credential.credential_id,
+    authority_kind: normalizeString(payload.authority_kind, "delegated_runtime_spend"),
+    spend_posture: credential.spend_posture,
+    scope: credential.scope,
+    authority_scope: ensureArray(payload.authority_scope).map((value) => String(value || "").trim()).filter(Boolean),
+    allowed_consequence_families: ensureArray(payload.allowed_consequence_families).map((value) => String(value || "").trim()).filter(Boolean),
+    consequence_bounds: {
+      max_commit_units: Number.isFinite(Number(payload.max_commit_units)) ? Number(payload.max_commit_units) : null,
+      max_reserve_units: Number.isFinite(Number(payload.max_reserve_units)) ? Number(payload.max_reserve_units) : null,
+      max_reversal_units: Number.isFinite(Number(payload.max_reversal_units)) ? Number(payload.max_reversal_units) : null
+    },
+    agent_id: credential.agent_id,
+    budget_id: credential.budget_id,
+    pack_id: credential.pack_id || null,
+    entitlement_id: credential.entitlement_id || null,
+    status: normalizeString(payload.status, "active"),
+    issued_by: normalizeString(payload.issued_by, "operator"),
+    labels: ensureArray(payload.labels),
+    expires_at_iso: credential.expires_at_iso,
+    rotated_from_binding_id: normalizeString(payload.rotated_from_binding_id, null),
+    replaced_by_binding_id: normalizeString(payload.replaced_by_binding_id, null),
+    created_at_iso: createdAtIso,
+    updated_at_iso: createdAtIso,
+    revoked_at_iso: null,
+    revoke_reason: null
+  };
+  state.accountAuthorityBindings.set(bindingId, binding);
+  return buildAuthorityBindingPublicView(binding, state.accountSpendCredentials.get(credential.credential_id), true);
+}
+
 function listSpendCredentials(state, filters) {
   const payload = ensureObject(filters);
   const accountId = normalizeString(payload.account_id, null);
@@ -102,6 +231,116 @@ function getSpendCredential(state, credentialId) {
   return buildCredentialPublicView(state.accountSpendCredentials.get(credentialId), false);
 }
 
+function listAuthorityBindings(state, filters) {
+  const payload = ensureObject(filters);
+  const accountId = normalizeString(payload.account_id, null);
+  const status = normalizeString(payload.status, null);
+  return Array.from(state.accountAuthorityBindings.values())
+    .filter((binding) => {
+      if (accountId && binding.account_id !== accountId) return false;
+      if (status && binding.status !== status) return false;
+      return true;
+    })
+    .map((binding) => buildAuthorityBindingPublicView(binding, state.accountSpendCredentials.get(binding.credential_id), false));
+}
+
+function getAuthorityBinding(state, bindingId) {
+  if (!bindingId || !state.accountAuthorityBindings.has(bindingId)) return null;
+  const binding = state.accountAuthorityBindings.get(bindingId);
+  return buildAuthorityBindingPublicView(binding, state.accountSpendCredentials.get(binding.credential_id), false);
+}
+
+function getAuthorityBindingContractSummary(state, bindingId) {
+  if (!bindingId || !state.accountAuthorityBindings.has(bindingId)) return null;
+  const binding = state.accountAuthorityBindings.get(bindingId);
+  return buildAuthorityBindingContractSummary(binding, state.accountSpendCredentials.get(binding.credential_id));
+}
+
+function getAuthorityBindingRotationSummary(state, bindingId) {
+  if (!bindingId || !state.accountAuthorityBindings.has(bindingId)) return null;
+  const binding = state.accountAuthorityBindings.get(bindingId);
+  return buildAuthorityBindingRotationSummary(binding, state.accountSpendCredentials.get(binding.credential_id));
+}
+
+function evaluateAuthorityBindingAction(binding, action, units) {
+  const target = binding && typeof binding === "object" ? binding : null;
+  const numericUnits = Number.isFinite(Number(units)) ? Number(units) : 0;
+  const allowedScopes = target ? ensureArray(target.authority_scope) : [];
+  const allowedFamilies = target ? ensureArray(target.allowed_consequence_families) : [];
+  const bounds = target && target.consequence_bounds ? target.consequence_bounds : {};
+
+  if (!target) {
+    return { ok: true };
+  }
+  if (target.status !== "active") {
+    return { ok: false, reason: "authority_binding_inactive", binding_id: target.binding_id };
+  }
+
+  const scopeMap = {
+    delegated_credit_spend: "runtime.execute",
+    reserve: "economics.reserve",
+    release: "economics.release",
+    reverse: "economics.reverse"
+  };
+  const familyMap = {
+    delegated_credit_spend: "commit",
+    reserve: "reserve",
+    release: "release",
+    reverse: "reverse"
+  };
+  const boundKeyMap = {
+    delegated_credit_spend: "max_commit_units",
+    reserve: "max_reserve_units",
+    reverse: "max_reversal_units"
+  };
+
+  const requiredScope = scopeMap[action] || null;
+  if (requiredScope && allowedScopes.length > 0 && !allowedScopes.includes(requiredScope)) {
+    return {
+      ok: false,
+      reason: "authority_scope_not_allowed",
+      binding_id: target.binding_id,
+      required_scope: requiredScope,
+      authority_scope: allowedScopes
+    };
+  }
+
+  const requiredFamily = familyMap[action] || null;
+  if (requiredFamily && allowedFamilies.length > 0 && !allowedFamilies.includes(requiredFamily)) {
+    return {
+      ok: false,
+      reason: "authority_consequence_family_not_allowed",
+      binding_id: target.binding_id,
+      required_consequence_family: requiredFamily,
+      allowed_consequence_families: allowedFamilies
+    };
+  }
+
+  const boundKey = boundKeyMap[action] || null;
+  if (boundKey && Number.isFinite(Number(bounds[boundKey])) && numericUnits > Number(bounds[boundKey])) {
+    return {
+      ok: false,
+      reason: "authority_consequence_bound_exceeded",
+      binding_id: target.binding_id,
+      bound_key: boundKey,
+      max_units: Number(bounds[boundKey]),
+      attempted_units: numericUnits
+    };
+  }
+
+  return {
+    ok: true,
+    binding_id: target.binding_id,
+    authority_scope: allowedScopes,
+    allowed_consequence_families: allowedFamilies,
+    consequence_bounds: {
+      max_commit_units: Number.isFinite(Number(bounds.max_commit_units)) ? Number(bounds.max_commit_units) : null,
+      max_reserve_units: Number.isFinite(Number(bounds.max_reserve_units)) ? Number(bounds.max_reserve_units) : null,
+      max_reversal_units: Number.isFinite(Number(bounds.max_reversal_units)) ? Number(bounds.max_reversal_units) : null
+    }
+  };
+}
+
 function revokeSpendCredential(state, credentialId, body) {
   if (!credentialId || !state.accountSpendCredentials.has(credentialId)) return null;
   const payload = ensureObject(body);
@@ -117,6 +356,94 @@ function revokeSpendCredential(state, credentialId, body) {
   return buildCredentialPublicView(next, false);
 }
 
+function revokeAuthorityBinding(state, bindingId, body) {
+  if (!bindingId || !state.accountAuthorityBindings.has(bindingId)) return null;
+  const payload = ensureObject(body);
+  const current = state.accountAuthorityBindings.get(bindingId);
+  const next = {
+    ...current,
+    status: "revoked",
+    revoked_at_iso: nowIso(),
+    revoke_reason: normalizeString(payload.reason, "operator_revoked"),
+    updated_at_iso: nowIso()
+  };
+  state.accountAuthorityBindings.set(bindingId, next);
+  if (current.credential_id) {
+    revokeSpendCredential(state, current.credential_id, payload);
+  }
+  return buildAuthorityBindingPublicView(next, current.credential_id ? state.accountSpendCredentials.get(current.credential_id) : null, false);
+}
+
+function renewAuthorityBinding(state, bindingId, body) {
+  if (!bindingId || !state.accountAuthorityBindings.has(bindingId)) return null;
+  const payload = ensureObject(body);
+  const current = state.accountAuthorityBindings.get(bindingId);
+  const nextExpiresAtIso = normalizeString(payload.expires_at_iso, current.expires_at_iso || null);
+  const updatedAtIso = nowIso();
+  const next = {
+    ...current,
+    expires_at_iso: nextExpiresAtIso,
+    updated_at_iso: updatedAtIso
+  };
+  state.accountAuthorityBindings.set(bindingId, next);
+  if (current.credential_id && state.accountSpendCredentials.has(current.credential_id)) {
+    const credential = state.accountSpendCredentials.get(current.credential_id);
+    state.accountSpendCredentials.set(current.credential_id, {
+      ...credential,
+      expires_at_iso: nextExpiresAtIso,
+      updated_at_iso: updatedAtIso
+    });
+  }
+  return buildAuthorityBindingPublicView(next, current.credential_id ? state.accountSpendCredentials.get(current.credential_id) : null, false);
+}
+
+function rotateAuthorityBinding(state, bindingId, body) {
+  if (!bindingId || !state.accountAuthorityBindings.has(bindingId)) return null;
+  const payload = ensureObject(body);
+  const current = state.accountAuthorityBindings.get(bindingId);
+  const currentCredential = current.credential_id ? state.accountSpendCredentials.get(current.credential_id) : null;
+  const successorBindingId = normalizeString(payload.successor_binding_id, `${bindingId}_rotated`);
+  const successorCredentialId = normalizeString(payload.successor_credential_id, current.credential_id ? `${current.credential_id}_rotated` : `spend_for_${successorBindingId}`);
+  const successor = createAuthorityBinding(state, {
+    binding_id: successorBindingId,
+    credential_id: successorCredentialId,
+    bearer_token: normalizeString(payload.bearer_token, null),
+    account_id: current.account_id,
+    agent_id: normalizeString(payload.agent_id, current.agent_id),
+    budget_id: normalizeString(payload.budget_id, current.budget_id),
+    pack_id: normalizeString(payload.pack_id, current.pack_id),
+    entitlement_id: normalizeString(payload.entitlement_id, current.entitlement_id),
+    scope: normalizeString(payload.scope, current.scope),
+    authority_kind: normalizeString(payload.authority_kind, current.authority_kind),
+    authority_scope: ensureArray(payload.authority_scope).length > 0 ? ensureArray(payload.authority_scope) : ensureArray(current.authority_scope),
+    allowed_consequence_families: ensureArray(payload.allowed_consequence_families).length > 0 ? ensureArray(payload.allowed_consequence_families) : ensureArray(current.allowed_consequence_families),
+    max_commit_units: Number.isFinite(Number(payload.max_commit_units)) ? Number(payload.max_commit_units) : current.consequence_bounds.max_commit_units,
+    max_reserve_units: Number.isFinite(Number(payload.max_reserve_units)) ? Number(payload.max_reserve_units) : current.consequence_bounds.max_reserve_units,
+    max_reversal_units: Number.isFinite(Number(payload.max_reversal_units)) ? Number(payload.max_reversal_units) : current.consequence_bounds.max_reversal_units,
+    labels: ensureArray(payload.labels).length > 0 ? ensureArray(payload.labels) : ensureArray(current.labels),
+    issued_by: normalizeString(payload.issued_by, current.issued_by || "operator"),
+    expires_at_iso: normalizeString(payload.expires_at_iso, current.expires_at_iso || (currentCredential ? currentCredential.expires_at_iso : null)),
+    rotated_from_binding_id: current.binding_id
+  });
+  const revoked = revokeAuthorityBinding(state, bindingId, {
+    reason: normalizeString(payload.reason, "rotated_to_successor")
+  });
+  const successorRecord = state.accountAuthorityBindings.get(successor.binding_id);
+  state.accountAuthorityBindings.set(successor.binding_id, {
+    ...successorRecord,
+    rotated_from_binding_id: current.binding_id
+  });
+  state.accountAuthorityBindings.set(bindingId, {
+    ...state.accountAuthorityBindings.get(bindingId),
+    replaced_by_binding_id: successor.binding_id
+  });
+  return {
+    rotated_binding: buildAuthorityBindingPublicView(state.accountAuthorityBindings.get(bindingId), current.credential_id ? state.accountSpendCredentials.get(current.credential_id) : null, false),
+    successor_authority_binding: buildAuthorityBindingPublicView(state.accountAuthorityBindings.get(successor.binding_id), state.accountSpendCredentials.get(successor.credential_id), true),
+    previous_view: revoked
+  };
+}
+
 function resolveSpendCredential(state, bearerToken) {
   const token = normalizeString(bearerToken, null);
   if (!token) {
@@ -147,26 +474,45 @@ function resolveSpendCredential(state, bearerToken) {
       credential: buildCredentialPublicView(credential, false)
     };
   }
+  const binding = Array.from(state.accountAuthorityBindings.values()).find((entry) => entry && entry.credential_id === credentialId && entry.status === "active") || null;
   return {
     ok: true,
     credential,
+    binding,
     authorization_context: {
       verification_mode: "delegated_spend_credential",
       wallet_id: credential.credential_id,
       payment_payload: {
+        binding_id: binding ? binding.binding_id : null,
         credential_id: credential.credential_id,
         spend_posture: credential.spend_posture,
         pack_id: credential.pack_id || null,
-        entitlement_id: credential.entitlement_id || null
+        entitlement_id: credential.entitlement_id || null,
+        authority_scope: binding ? ensureArray(binding.authority_scope) : [],
+        allowed_consequence_families: binding ? ensureArray(binding.allowed_consequence_families) : [],
+        consequence_bounds: binding && binding.consequence_bounds ? binding.consequence_bounds : {
+          max_commit_units: null,
+          max_reserve_units: null,
+          max_reversal_units: null
+        }
       }
     }
   };
 }
 
 module.exports = {
+  createAuthorityBinding,
   createSpendCredential,
+  evaluateAuthorityBindingAction,
+  getAuthorityBinding,
+  getAuthorityBindingContractSummary,
+  getAuthorityBindingRotationSummary,
   getSpendCredential,
+  listAuthorityBindings,
   listSpendCredentials,
+  renewAuthorityBinding,
   resolveSpendCredential,
+  rotateAuthorityBinding,
+  revokeAuthorityBinding,
   revokeSpendCredential
 };