chainlesschain 0.166.2 → 0.166.4

package/src/lib/app-server/cli-agent-kernel-adapter.js

@@ -162,6 +162,7 @@ export class CliAgentKernelAdapter {
             type: "approval",
             id: event.id,
             approve: approvalBoolean(decision),
+            decision,
             binding: event.binding,
           });
         }

package/src/lib/app-server/protocol.js

@@ -1,13 +1,6 @@
-import { readFileSync } from "node:fs";
+import schema from "../../generated/cc-agent-protocol.schema.json" with { type: "json" };
 import { validate } from "../json-schema-validate.js";
 
-const schema = JSON.parse(
-  readFileSync(
-    new URL("../../generated/cc-agent-protocol.schema.json", import.meta.url),
-    "utf8",
-  ),
-);
-
 export const APP_SERVER_PROTOCOL_VERSION = schema["x-cc-protocol"].version;
 export const APP_SERVER_MIN_PROTOCOL_VERSION =
   schema["x-cc-protocol"].minimumCompatibleVersion;
@@ -53,6 +46,49 @@ export function validateAppServerMessage(value) {
   });
 }
 
+const definitionSchemas = new Map();
+
+/** Validate one canonical $defs value without maintaining a second hand-written union. */
+export function validateAppServerDefinition(name, value) {
+  const definition = APP_SERVER_SCHEMA.$defs?.[name];
+  if (!definition) {
+    return Object.freeze({
+      ok: false,
+      errors: Object.freeze([
+        Object.freeze({
+          path: "#",
+          message: `unknown protocol definition ${String(name)}`,
+        }),
+      ]),
+    });
+  }
+  let definitionSchema = definitionSchemas.get(name);
+  if (!definitionSchema) {
+    definitionSchema = {
+      $schema: APP_SERVER_SCHEMA.$schema,
+      $ref: `#/$defs/${name}`,
+      $defs: APP_SERVER_SCHEMA.$defs,
+    };
+    definitionSchemas.set(name, definitionSchema);
+  }
+  const result = validate(value, definitionSchema);
+  return Object.freeze({
+    ok: result.valid,
+    errors: Object.freeze(
+      result.errors.map((error) =>
+        Object.freeze({
+          path: error.instancePath || error.schemaPath || "#",
+          message: error.message || error.code || "invalid value",
+        }),
+      ),
+    ),
+  });
+}
+
+export function validateApprovalDecision(value) {
+  return validateAppServerDefinition("ApprovalDecision", value);
+}
+
 export function rpcResult(id, result) {
   return { jsonrpc: "2.0", id, result: result ?? null };
 }

package/src/lib/app-server/server.js

@@ -12,6 +12,7 @@ import {
   rpcError,
   rpcNotification,
   rpcResult,
+  validateApprovalDecision,
   validateAppServerMessage,
 } from "./protocol.js";
 
@@ -746,28 +747,24 @@ export class CcAppServer {
         ? event.risk
         : "high",
       reason: event.reason || "The Agent Kernel requires approval",
-      requestedPermissions: [],
+      requestedPermissions: Array.isArray(event.requested_permissions)
+        ? event.requested_permissions
+        : [],
     };
   }
 
   async _requestApproval(turn, event) {
     const request = this._approvalRequest(turn, event);
     const result = await this._requestClient("approval/decide", { request });
-    const decision = requireObject(result, "approval decision");
-    const allowed = new Set([
-      "acceptOnce",
-      "acceptForTurn",
-      "acceptForSession",
-      "decline",
-      "cancel",
-    ]);
-    if (!allowed.has(decision.kind)) {
+    const validation = validateApprovalDecision(result);
+    if (!validation.ok) {
       throw new JsonRpcError(
         JSON_RPC_ERROR.INVALID_PARAMS,
         "client returned an invalid approval decision",
+        { errors: validation.errors },
       );
     }
-    return decision;
+    return result;
   }
 
   async _completeTurn(turn, status, result) {

package/src/lib/approval-grant-ledger.js

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import { validateAppServerDefinition } from "./app-server/protocol.js";
+
+export const APPROVAL_GRANTS_EVENT = "approval_grants";
+export const APPROVAL_GRANTS_SCHEMA = "chainlesschain.approval-grants/v1";
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort()
+      .map((key) => [key, stableValue(value[key])]),
+  );
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function boundedScope(value) {
+  const serialized = stableJson(value);
+  if (serialized.length <= 1024) return serialized;
+  return `sha256:${createHash("sha256").update(serialized).digest("hex")}`;
+}
+
+function boundedCapability(tool) {
+  const candidate = `tool:${String(tool || "unknown")}`;
+  if (candidate.length <= 128) return candidate;
+  return `tool:sha256:${createHash("sha256").update(candidate).digest("hex")}`;
+}
+
+export function approvalPermissionForContext(ctx = {}, { cwd = null } = {}) {
+  const tool = ctx.tool || ctx.toolName || ctx.name || "unknown";
+  const args =
+    ctx.args ?? (ctx.command != null ? { command: ctx.command } : null);
+  const policy = ctx.rule || ctx.riskLevel || ctx.risk || null;
+  return Object.freeze({
+    capability: boundedCapability(tool),
+    scope: boundedScope({ cwd: cwd || ctx.cwd || null, args, policy }),
+  });
+}
+
+function permissionKey(permission) {
+  return `${permission.capability}\0${permission.scope}`;
+}
+
+function livePermission(permission, now) {
+  const validation = validateAppServerDefinition("PermissionGrant", permission);
+  if (!validation.ok) return false;
+  return !permission.expiresAt || Date.parse(permission.expiresAt) > now;
+}
+
+function samePermission(left, right) {
+  return permissionKey(left) === permissionKey(right);
+}
+
+function normalizePersistedEntry(entry, now) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+  if (!livePermission(entry.permission, now)) return null;
+  if (
+    typeof entry.binding !== "string" ||
+    !entry.binding ||
+    typeof entry.grantedAt !== "string" ||
+    Number.isNaN(Date.parse(entry.grantedAt))
+  ) {
+    return null;
+  }
+  return Object.freeze({
+    permission: Object.freeze({ ...entry.permission }),
+    binding: entry.binding,
+    grantedAt: entry.grantedAt,
+  });
+}
+
+export class ApprovalGrantLedger {
+  constructor({ sessionId, now = () => Date.now() } = {}) {
+    if (!sessionId) throw new TypeError("approval grant sessionId is required");
+    this.sessionId = String(sessionId);
+    this.now = now;
+    this.turnId = null;
+    this.turnGrants = new Map();
+    this.sessionGrants = new Map();
+    this.revision = 0;
+  }
+
+  beginTurn(turnId) {
+    this.turnId = String(turnId);
+    this.turnGrants.clear();
+  }
+
+  allows(permission) {
+    const now = this.now();
+    const key = permissionKey(permission);
+    for (const grants of [this.turnGrants, this.sessionGrants]) {
+      const entry = grants.get(key);
+      if (!entry) continue;
+      if (livePermission(entry.permission, now)) return true;
+      grants.delete(key);
+    }
+    return false;
+  }
+
+  applyDecision(decision, requiredPermission, binding) {
+    if (
+      decision?.kind !== "acceptForTurn" &&
+      decision?.kind !== "acceptForSession"
+    ) {
+      return Object.freeze({
+        decision,
+        granted: Object.freeze([]),
+        persistedScope: false,
+      });
+    }
+    const candidates =
+      decision.permissions === undefined
+        ? [requiredPermission]
+        : decision.permissions;
+    const target =
+      decision.kind === "acceptForSession"
+        ? this.sessionGrants
+        : this.turnGrants;
+    const granted = candidates
+      .filter(
+        (permission) =>
+          livePermission(permission, this.now()) &&
+          samePermission(permission, requiredPermission) &&
+          (target.has(permissionKey(permission)) || target.size < 64),
+      )
+      .slice(0, 1)
+      .map((permission) => Object.freeze({ ...permission }));
+    const grantedAt = new Date(this.now()).toISOString();
+    for (const permission of granted) {
+      target.set(
+        permissionKey(permission),
+        Object.freeze({ permission, binding, grantedAt }),
+      );
+    }
+    if (granted.length) this.revision += 1;
+    return Object.freeze({
+      decision: Object.freeze({ ...decision, permissions: granted }),
+      granted: Object.freeze(granted),
+      persistedScope:
+        decision.kind === "acceptForSession" && granted.length > 0,
+    });
+  }
+
+  toJSON() {
+    return {
+      schema: APPROVAL_GRANTS_SCHEMA,
+      sessionId: this.sessionId,
+      revision: this.revision,
+      grants: [...this.sessionGrants.values()].map((entry) => ({
+        permission: { ...entry.permission },
+        binding: entry.binding,
+        grantedAt: entry.grantedAt,
+      })),
+    };
+  }
+
+  static fromJSON(value, { sessionId, now = () => Date.now() } = {}) {
+    const ledger = new ApprovalGrantLedger({ sessionId, now });
+    if (
+      !value ||
+      typeof value !== "object" ||
+      Array.isArray(value) ||
+      value.schema !== APPROVAL_GRANTS_SCHEMA ||
+      value.sessionId !== ledger.sessionId ||
+      !Number.isSafeInteger(value.revision) ||
+      value.revision < 0 ||
+      !Array.isArray(value.grants) ||
+      value.grants.length > 64
+    ) {
+      throw new TypeError("invalid persisted approval grant ledger");
+    }
+    for (const candidate of value.grants) {
+      const entry = normalizePersistedEntry(candidate, now());
+      if (!entry) {
+        throw new TypeError("invalid persisted approval grant entry");
+      }
+      ledger.sessionGrants.set(permissionKey(entry.permission), entry);
+    }
+    ledger.revision = value.revision;
+    return ledger;
+  }
+}

package/src/lib/remote-approval-bridge.js

@@ -52,6 +52,7 @@ import {
   resolveRemoteControlWsUrl,
 } from "./remote-control.js";
 import { logger } from "./logger.js";
+import { normalizeRemoteApprovalDecision } from "./remote-approval-decision.js";
 
 const DEFAULT_DECISION_TIMEOUT_MS = 5 * 60 * 1000;
 const REMOTE_LEASE_AUTHORIZATION_KIND =
@@ -411,24 +412,19 @@ export class RemoteApprovalBridge {
     // The device must echo the complete durable capability tuple. Missing,
     // mismatched, stale, duplicate, or expired resolutions never settle an
     // approval; only the store's successful CAS can return approved=true.
-    const rawAnswer = message.event.answer ?? message.event.approved;
-    const hasDecision =
-      rawAnswer === true ||
-      rawAnswer === false ||
-      rawAnswer === "true" ||
-      rawAnswer === "false" ||
-      rawAnswer === "yes" ||
-      rawAnswer === "no";
-    if (!hasDecision) {
+    const remoteDecision = normalizeRemoteApprovalDecision(message.event, {
+      requireCanonical:
+        message.memberCapabilities?.includes("approval-decision-v1") === true,
+    });
+    if (!remoteDecision.ok) {
       this._recordSecurityError({
         action: "approval.resolve",
         requestId,
-        reason: "decision-required",
+        reason: remoteDecision.reason,
       });
       return;
     }
-    const decision =
-      rawAnswer === true || rawAnswer === "true" || rawAnswer === "yes";
+    const decision = remoteDecision.approved;
     let ackedLease = null;
     // The server creates the lease before forwarding the resolve frame. Keep a
     // strictly request-bound cancellation handle even when durable adoption of

package/src/lib/remote-approval-decision.js

@@ -0,0 +1,87 @@
+import { validateApprovalDecision } from "./app-server/protocol.js";
+
+export const REMOTE_APPROVAL_DECISION_CAPABILITY = "approval-decision-v1";
+
+const LEGACY_TRUE = new Set([true, "true", "yes"]);
+const LEGACY_FALSE = new Set([false, "false", "no"]);
+
+function parseLegacyValue(value) {
+  if (LEGACY_TRUE.has(value)) return true;
+  if (LEGACY_FALSE.has(value)) return false;
+  return null;
+}
+
+function invalid(reason) {
+  return Object.freeze({ ok: false, reason });
+}
+
+/**
+ * Normalize a remote approval response at the transport boundary.
+ *
+ * New clients send a canonical ApprovalDecision plus the N-1 boolean
+ * projection. Legacy clients may still send only answer/approved. Remote
+ * binary approval UIs cannot safely review scoped grants, so only acceptOnce
+ * and decline are admitted here.
+ */
+export function normalizeRemoteApprovalDecision(
+  event,
+  { requireCanonical = false } = {},
+) {
+  if (!event || typeof event !== "object" || Array.isArray(event)) {
+    return invalid("decision-required");
+  }
+
+  const hasCanonical = Object.prototype.hasOwnProperty.call(event, "decision");
+  let canonicalApproved = null;
+  let canonicalKind = null;
+  if (hasCanonical) {
+    const validation = validateApprovalDecision(event.decision);
+    if (!validation.ok) return invalid("canonical-decision-invalid");
+    canonicalKind = event.decision.kind;
+    if (canonicalKind === "acceptOnce") canonicalApproved = true;
+    else if (canonicalKind === "decline") canonicalApproved = false;
+    else return invalid("remote-decision-kind-not-supported");
+  } else if (requireCanonical) {
+    return invalid("canonical-decision-required");
+  }
+
+  const legacyValues = [];
+  for (const field of ["answer", "approved"]) {
+    const value = event[field];
+    // Preserve the old `answer ?? approved` behavior for a null answer.
+    if (value === null || value === undefined) continue;
+    const parsed = parseLegacyValue(value);
+    if (parsed === null) return invalid("legacy-decision-invalid");
+    legacyValues.push(parsed);
+  }
+  if (legacyValues.some((value) => value !== legacyValues[0])) {
+    return invalid("legacy-decision-conflict");
+  }
+  const legacyApproved = legacyValues.length > 0 ? legacyValues[0] : null;
+
+  if (canonicalApproved === null && legacyApproved === null) {
+    return invalid("decision-required");
+  }
+  if (
+    canonicalApproved !== null &&
+    legacyApproved !== null &&
+    canonicalApproved !== legacyApproved
+  ) {
+    return invalid("canonical-legacy-decision-conflict");
+  }
+
+  return Object.freeze({
+    ok: true,
+    approved: canonicalApproved ?? legacyApproved,
+    kind: canonicalKind || (legacyApproved === true ? "acceptOnce" : "decline"),
+    canonical: hasCanonical,
+  });
+}
+
+export function requireRemoteApprovalDecision(event, options) {
+  const result = normalizeRemoteApprovalDecision(event, options);
+  if (!result.ok) {
+    throw new TypeError(`Invalid remote approval decision: ${result.reason}`);
+  }
+  return result;
+}