@vellumai/assistant 0.3.26 → 0.3.28

package/src/approvals/guardian-decision-primitive.ts

@@ -12,6 +12,11 @@
  *   5. Guardian approval record update
  *   6. Scoped grant minting on approve
  *
+ * The canonical path (`applyCanonicalGuardianDecision`) adds:
+ *   7. Canonical request lookup and status validation
+ *   8. CAS resolution via `resolveCanonicalGuardianRequest`
+ *   9. Kind-specific resolver dispatch via the resolver registry
+ *
  * Security invariants enforced here:
  *   - Decision application is identity-bound to expected guardian identity
  *   - Decisions are first-response-wins (CAS-like stale protection)
@@ -20,11 +25,18 @@
  */
 
 import type { ChannelId } from '../channels/types.js';
+import {
+  type CanonicalGuardianRequest,
+  type CanonicalRequestStatus,
+  getCanonicalGuardianRequest,
+  resolveCanonicalGuardianRequest,
+} from '../memory/canonical-guardian-store.js';
 import {
   type GuardianApprovalRequest,
   updateApprovalDecision,
 } from '../memory/channel-guardian-store.js';
 import type {
+  ApprovalAction,
   ApprovalDecisionResult,
 } from '../runtime/channel-approval-types.js';
 import {
@@ -36,6 +48,11 @@ import type { ApplyGuardianDecisionResult } from '../runtime/guardian-decision-t
 import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
 import { getLogger } from '../util/logger.js';
 import { mintGrantFromDecision } from './approval-primitive.js';
+import {
+  type ActorContext,
+  type ChannelDeliveryContext,
+  getResolver,
+} from './guardian-request-resolvers.js';
 
 const log = getLogger('guardian-decision-primitive');
 
@@ -189,3 +206,271 @@ export function applyGuardianDecision(params: ApplyGuardianDecisionParams): Appl
     requestId: result.requestId,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Consolidated canonical grant minting
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a scoped approval grant from a canonical guardian request.
+ *
+ * Works for all request kinds that carry tool metadata (toolName + inputDigest).
+ * Requests without tool metadata are silently skipped — grant minting only
+ * applies to tool-approval flows.
+ *
+ * Fails silently on error — grant minting is best-effort and must never
+ * block the approval flow.
+ */
+export function mintCanonicalRequestGrant(params: {
+  request: CanonicalGuardianRequest;
+  actorChannel: string;
+  guardianExternalUserId?: string;
+}): { minted: boolean } {
+  const { request, actorChannel, guardianExternalUserId } = params;
+
+  if (!request.toolName || !request.inputDigest) {
+    return { minted: false };
+  }
+
+  const result = mintGrantFromDecision({
+    assistantId: 'self',
+    scopeMode: 'tool_signature',
+    toolName: request.toolName,
+    inputDigest: request.inputDigest,
+    requestChannel: request.sourceChannel ?? 'unknown',
+    decisionChannel: actorChannel,
+    executionChannel: null,
+    conversationId: request.conversationId ?? null,
+    callSessionId: request.callSessionId ?? null,
+    guardianExternalUserId: guardianExternalUserId ?? null,
+    requesterExternalUserId: request.requesterExternalUserId ?? null,
+    expiresAt: new Date(Date.now() + GRANT_TTL_MS).toISOString(),
+  });
+
+  if (result.ok) {
+    log.info(
+      {
+        event: 'canonical_grant_minted',
+        requestId: request.id,
+        toolName: request.toolName,
+        conversationId: request.conversationId,
+      },
+      'Minted scoped approval grant for canonical guardian request',
+    );
+    return { minted: true };
+  }
+
+  log.error(
+    {
+      event: 'canonical_grant_mint_failed',
+      reason: result.reason,
+      requestId: request.id,
+      toolName: request.toolName,
+    },
+    'Failed to mint scoped approval grant for canonical request (non-fatal)',
+  );
+  return { minted: false };
+}
+
+// ---------------------------------------------------------------------------
+// Canonical guardian decision primitive
+// ---------------------------------------------------------------------------
+
+/** Valid actions for canonical guardian decisions. */
+const VALID_CANONICAL_ACTIONS: ReadonlySet<ApprovalAction> = new Set([
+  'approve_once',
+  'approve_always',
+  'reject',
+]);
+
+export interface ApplyCanonicalGuardianDecisionParams {
+  /** The canonical request ID to resolve. */
+  requestId: string;
+  /** The decision action. */
+  action: ApprovalAction;
+  /** Actor context for the entity making the decision. */
+  actorContext: ActorContext;
+  /** Optional user-supplied text (e.g. answer text for pending questions). */
+  userText?: string;
+  /** Optional channel delivery context — present when the decision arrived via a channel message. */
+  channelDeliveryContext?: ChannelDeliveryContext;
+}
+
+export type CanonicalDecisionResult =
+  | { applied: true; requestId: string; grantMinted: boolean; resolverFailed?: boolean; resolverFailureReason?: string }
+  | { applied: false; reason: 'not_found' | 'already_resolved' | 'identity_mismatch' | 'invalid_action' | 'expired'; detail?: string };
+
+/**
+ * Apply a guardian decision through the canonical request primitive.
+ *
+ * This is the future single write path for all guardian decisions.  It
+ * operates on the canonical_guardian_requests table and dispatches to
+ * kind-specific resolvers via the resolver registry.
+ *
+ * Steps:
+ *   1. Look up the canonical request by ID
+ *   2. Validate: exists, pending status, identity match, valid action
+ *   3. Downgrade approve_always to approve_once (guardian-on-behalf invariant)
+ *   4. CAS resolve the canonical request atomically
+ *   5. Dispatch to kind-specific resolver
+ *   6. Mint grant if applicable
+ */
+export async function applyCanonicalGuardianDecision(
+  params: ApplyCanonicalGuardianDecisionParams,
+): Promise<CanonicalDecisionResult> {
+  const { requestId, action, actorContext, userText, channelDeliveryContext } = params;
+
+  // 1. Look up the canonical request
+  const request = getCanonicalGuardianRequest(requestId);
+  if (!request) {
+    log.warn(
+      { event: 'canonical_decision_not_found', requestId },
+      'Canonical request not found',
+    );
+    return { applied: false, reason: 'not_found' };
+  }
+
+  // 2a. Validate status is pending
+  if (request.status !== 'pending') {
+    log.info(
+      { event: 'canonical_decision_already_resolved', requestId, currentStatus: request.status },
+      'Canonical request already resolved',
+    );
+    return { applied: false, reason: 'already_resolved' };
+  }
+
+  // 2b. Validate action is valid
+  if (!VALID_CANONICAL_ACTIONS.has(action)) {
+    log.warn(
+      { event: 'canonical_decision_invalid_action', requestId, action },
+      'Invalid action for canonical decision',
+    );
+    return { applied: false, reason: 'invalid_action', detail: `invalid action: ${action}` };
+  }
+
+  // 2c. Validate identity: actor must match guardian_external_user_id
+  // unless the actor is trusted (desktop) or the request has no guardian binding.
+  if (
+    request.guardianExternalUserId &&
+    !actorContext.isTrusted &&
+    actorContext.externalUserId !== request.guardianExternalUserId
+  ) {
+    log.warn(
+      {
+        event: 'canonical_decision_identity_mismatch',
+        requestId,
+        expectedGuardian: request.guardianExternalUserId,
+        actualActor: actorContext.externalUserId,
+      },
+      'Actor identity does not match expected guardian',
+    );
+    return { applied: false, reason: 'identity_mismatch' };
+  }
+
+  // 2d. Check expiry
+  if (request.expiresAt && new Date(request.expiresAt).getTime() < Date.now()) {
+    log.info(
+      { event: 'canonical_decision_expired', requestId, expiresAt: request.expiresAt },
+      'Canonical request has expired',
+    );
+    return { applied: false, reason: 'expired' };
+  }
+
+  // 3. Downgrade approve_always to approve_once for guardian-on-behalf requests.
+  // Guardians cannot permanently allowlist tools on behalf of requesters.
+  const effectiveAction: ApprovalAction = action === 'approve_always'
+    ? 'approve_once'
+    : action;
+
+  // 4. CAS resolve: atomically transition from 'pending' to terminal status
+  const targetStatus: CanonicalRequestStatus = effectiveAction === 'reject'
+    ? 'denied'
+    : 'approved';
+
+  const resolved = resolveCanonicalGuardianRequest(requestId, 'pending', {
+    status: targetStatus,
+    answerText: userText,
+    decidedByExternalUserId: actorContext.externalUserId,
+  });
+
+  if (!resolved) {
+    // CAS failed — someone else resolved it first
+    log.info(
+      { event: 'canonical_decision_cas_failed', requestId },
+      'CAS resolution failed (race condition — first writer wins)',
+    );
+    return { applied: false, reason: 'already_resolved' };
+  }
+
+  // 5. Dispatch to kind-specific resolver
+  let resolverFailed = false;
+  let resolverFailureReason: string | undefined;
+  const resolver = getResolver(request.kind);
+  if (resolver) {
+    const resolverResult = await resolver.resolve({
+      request: resolved,
+      decision: { action: effectiveAction, userText },
+      actor: actorContext,
+      channelDeliveryContext,
+    });
+
+    if (!resolverResult.ok) {
+      log.warn(
+        {
+          event: 'canonical_decision_resolver_failed',
+          requestId,
+          kind: request.kind,
+          reason: resolverResult.reason,
+        },
+        `Resolver for kind '${request.kind}' failed: ${resolverResult.reason}`,
+      );
+      // The canonical request is already resolved (CAS succeeded), so we don't
+      // roll back.  Flag the failure and fall through to grant minting so that
+      // callers see applied: true (reflecting the committed DB state) while
+      // still being informed that the resolver had an issue.
+      resolverFailed = true;
+      resolverFailureReason = resolverResult.reason;
+    }
+  } else {
+    log.info(
+      { event: 'canonical_decision_no_resolver', requestId, kind: request.kind },
+      `No resolver registered for kind '${request.kind}' — CAS resolution only`,
+    );
+  }
+
+  // 6. Mint grant if the decision is an approval with tool metadata.
+  // Skip when the resolver failed — minting a grant on a failed side effect
+  // would allow the tool to execute without the intended resolver action
+  // (e.g. answerCall) having succeeded.
+  let grantMinted = false;
+  if (effectiveAction !== 'reject' && !resolverFailed) {
+    const grantResult = mintCanonicalRequestGrant({
+      request: resolved,
+      actorChannel: actorContext.channel,
+      guardianExternalUserId: actorContext.externalUserId ?? resolved.guardianExternalUserId ?? undefined,
+    });
+    grantMinted = grantResult.minted;
+  }
+
+  log.info(
+    {
+      event: 'canonical_decision_applied',
+      requestId,
+      kind: request.kind,
+      action: effectiveAction,
+      targetStatus,
+      grantMinted,
+      resolverFailed,
+    },
+    resolverFailed
+      ? 'Canonical guardian decision applied (CAS committed) but resolver failed'
+      : 'Canonical guardian decision applied successfully',
+  );
+
+  return {
+    applied: true,
+    requestId,
+    grantMinted,
+    ...(resolverFailed ? { resolverFailed, resolverFailureReason } : {}),
+  };
+}