@brainai/satp-client 2.0.2 → 2.0.4

package/src/index.js

@@ -787,10 +787,16 @@ const {
   DECISIONS,
   DEFAULT_POLICY,
   REASON_CODES,
+  RUNTIME_POLICY_AUDIT_TRACE_SCHEMA_VERSION,
+  RUNTIME_POLICY_HOST_ACTION_DESCRIPTOR_SCHEMA_VERSION,
+  buildRuntimePolicyActionDescriptor,
+  buildRuntimePolicyAuditTrace,
+  createRuntimePolicyAdapter,
   evaluateRuntimePolicy,
 } = require('./runtime-policy-adapter');
 const walletControlChallenge = require('./wallet-control-challenge');
 const x402Discovery = require('./x402-discovery');
+const signerPolicy = require('./signer-policy');
 
 // Legacy V3 SDK wrapper — keeps string constructor compatibility while using
 // the local extracted SATPV3SDK implementation so offline tests and consumers
@@ -905,7 +911,12 @@ module.exports = {
 
   // V3 PDA derivation (local extracted scaffold)
   PROGRAM_IDS: v3pda.getV3ProgramIds('devnet'),
+  V3_DEVNET_PROGRAM_IDS: v3pda.V3_DEVNET_PROGRAM_IDS,
+  V3_MAINNET_PROGRAM_IDS: v3pda.V3_MAINNET_PROGRAM_IDS,
   getV3ProgramIds: v3pda.getV3ProgramIds,
+  V3_DEVNET_TOKEN_MINTS: v3pda.V3_DEVNET_TOKEN_MINTS,
+  SPL_TOKEN_PROGRAM_ID: v3pda.SPL_TOKEN_PROGRAM_ID,
+  ASSOCIATED_TOKEN_PROGRAM_ID: v3pda.ASSOCIATED_TOKEN_PROGRAM_ID,
   hashAgentId: v3pda.hashAgentId,
   agentIdHash: v3pda.hashAgentId,
   hashName: v3pda.hashName,
@@ -929,6 +940,8 @@ module.exports = {
   deriveAttestationPda: v3pda.getV3AttestationPDA,
   getV3EscrowPDA: v3pda.getV3EscrowPDA,
   deriveEscrowPda: v3pda.getV3EscrowPDA,
+  getAssociatedTokenAddress: v3pda.getAssociatedTokenAddress,
+  getV3EscrowVaultATA: v3pda.getV3EscrowVaultATA,
   deriveReviewAttestationPda: getReviewAttestationPDA,
   prepareIdentityAttestationRequest,
   TRUST_PACKET_SCHEMA_VERSION,
@@ -950,11 +963,21 @@ module.exports = {
   buildX402EvidenceLookup: x402Discovery.buildX402EvidenceLookup,
   buildRuntimePolicyActionDescriptorFromX402Discovery: x402Discovery.buildRuntimePolicyActionDescriptorFromX402Discovery,
   buildRuntimePolicyActionDescriptorFromX402: x402Discovery.buildRuntimePolicyActionDescriptorFromX402,
+  SATP_SIGNER_ROLES: signerPolicy.SATP_SIGNER_ROLES,
+  OPERATIONAL_SIGNER_ALLOWED_ACTIONS: signerPolicy.OPERATIONAL_SIGNER_ALLOWED_ACTIONS,
+  OWNER_UPGRADE_AUTHORITY_BLOCKED_ACTIONS: signerPolicy.OWNER_UPGRADE_AUTHORITY_BLOCKED_ACTIONS,
+  buildSignerSeparationConfig: signerPolicy.buildSignerSeparationConfig,
+  validateSignerSeparationConfig: signerPolicy.validateSignerSeparationConfig,
 
   // Runtime policy adapter (offline/local guardrail helper)
   DECISIONS,
   DEFAULT_POLICY,
   REASON_CODES,
+  RUNTIME_POLICY_AUDIT_TRACE_SCHEMA_VERSION,
+  RUNTIME_POLICY_HOST_ACTION_DESCRIPTOR_SCHEMA_VERSION,
+  buildRuntimePolicyActionDescriptor,
+  buildRuntimePolicyAuditTrace,
+  createRuntimePolicyAdapter,
   evaluateRuntimePolicy,
 
   // V3 Deserialization (local extracted scaffold)

package/src/runtime-policy-adapter.js

@@ -34,6 +34,62 @@ const DEFAULT_POLICY = Object.freeze({
   staleEvidenceAfterMs: 7 * 24 * 60 * 60 * 1000,
 });
 
+const RUNTIME_POLICY_AUDIT_TRACE_SCHEMA_VERSION = 'satp.runtimePolicyAuditTrace.v1';
+const RUNTIME_POLICY_HOST_ACTION_DESCRIPTOR_SCHEMA_VERSION = 'satp.runtimePolicyHostActionDescriptor.v1';
+
+function createRuntimePolicyAdapter(config = {}) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error('runtime policy adapter config must be an object');
+  }
+
+  const adapterPolicy = normalizePolicy(config.policy);
+  const defaultActionType = config.defaultActionType || null;
+  const nowProvider = config.now;
+  const redact = config.redact;
+
+  if (nowProvider !== undefined && typeof nowProvider !== 'function' && !isValidDateInput(nowProvider)) {
+    throw new Error('runtime policy adapter now must be a function or valid date input');
+  }
+  if (redact !== undefined && typeof redact !== 'function') {
+    throw new Error('runtime policy adapter redact must be a function');
+  }
+
+  function adapterOptions(options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new Error('runtime policy adapter method options must be an object');
+    }
+
+    return {
+      ...options,
+      now: resolveAdapterNow(nowProvider, options.now),
+      policy: {
+        ...adapterPolicy,
+        ...(options.policy || {}),
+      },
+    };
+  }
+
+  return Object.freeze({
+    action(input = {}, overrides = {}) {
+      const base = applyDefaultActionType(input, defaultActionType);
+      return buildRuntimePolicyActionDescriptor(base, overrides);
+    },
+
+    evaluate(identityPayload, actionDescriptor, options = {}) {
+      return evaluateRuntimePolicy(identityPayload, actionDescriptor, adapterOptions(options));
+    },
+
+    auditTrace(identityPayload, actionDescriptor, options = {}) {
+      const traceAction = redact ? attachRedactedResourceLabel(actionDescriptor, redact) : actionDescriptor;
+      return buildRuntimePolicyAuditTrace(identityPayload, traceAction, adapterOptions(options));
+    },
+
+    explain(result) {
+      return explainRuntimePolicyResult(result);
+    },
+  });
+}
+
 function evaluateRuntimePolicy(identityPayload, actionDescriptor, options = {}) {
   const policy = { ...DEFAULT_POLICY, ...(options.policy || {}) };
   const now = options.now ? new Date(options.now) : new Date();
@@ -109,6 +165,94 @@ function evaluateRuntimePolicy(identityPayload, actionDescriptor, options = {})
   return decision(DECISIONS.ALLOW, reasonCodes, checks, 'Local runtime policy allows the action.');
 }
 
+function buildRuntimePolicyAuditTrace(identityPayload, actionDescriptor, options = {}) {
+  const result = options.result || evaluateRuntimePolicy(identityPayload, actionDescriptor, options);
+  const identity = normalizeIdentity(identityPayload);
+  const action = normalizeAction(actionDescriptor);
+
+  return {
+    schemaVersion: RUNTIME_POLICY_AUDIT_TRACE_SCHEMA_VERSION,
+    mode: 'offline-local-runtime-policy-trace',
+    generatedAt: safeIsoDate(options.now),
+    decision: result.decision,
+    reasonCodes: result.reasonCodes.slice(),
+    message: result.message,
+    subject: {
+      agentId: identity.agentId,
+      active: identity.active,
+      verified: identity.verified,
+      trustScoreBand: trustScoreBand(identity.trustScore),
+      evidenceUpdatedAt: identity.evidenceUpdatedAt,
+      capabilityCount: identity.capabilities.length,
+    },
+    action: {
+      type: action.type,
+      operation: action.operation,
+      resourceKind: resourceKind(action.resource),
+      resourceLabel: action.resourceLabel,
+      requiresCapability: action.requiresCapability,
+      requiresFreshEvidence: action.requiresFreshEvidence,
+      protectedTool: action.protectedTool,
+      operatorApprovalRequired: action.operatorApprovalRequired,
+      costUsd: action.costUsd,
+      evidenceLookup: action.evidenceLookup
+        ? {
+            type: action.evidenceLookup.type || null,
+            configured: true,
+            maxCostUsd: action.evidenceLookup.maxCostUsd ?? null,
+          }
+        : null,
+    },
+    checks: sanitizeAuditChecks(result.checks),
+    guardrails: {
+      localDecisionOnly: true,
+      writesSolanaState: false,
+      usesKeypairs: false,
+      deploysPrograms: false,
+      publishesPackages: false,
+      authorizesPayment: false,
+      authorizesAgentActionFromPayment: false,
+    },
+  };
+}
+
+function buildRuntimePolicyActionDescriptor(input = {}, overrides = {}) {
+  const base = typeof input === 'string' ? { type: input } : input;
+  if (!base || typeof base !== 'object' || Array.isArray(base)) {
+    throw new Error('runtime policy action descriptor input must be an object or action type string');
+  }
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    throw new Error('runtime policy action descriptor overrides must be an object');
+  }
+
+  const action = { ...base, ...overrides };
+  const type = action.type || action.surface || 'generic';
+  const descriptor = {
+    schemaVersion: RUNTIME_POLICY_HOST_ACTION_DESCRIPTOR_SCHEMA_VERSION,
+    type,
+    resource: firstDefined(action.resource, defaultResourceForAction(type, action)),
+    operation: firstDefined(action.operation, defaultOperationForAction(type)),
+    requiresCapability: firstDefined(action.requiresCapability, action.capability, defaultCapabilityForAction(type)),
+    minimumTrustScore: firstDefined(action.minimumTrustScore, action.trustScoreMinimum, defaultMinimumTrustScoreForAction(type)),
+    allowDegraded: firstDefined(action.allowDegraded, defaultAllowDegradedForAction(type)),
+    requiresFreshEvidence: firstDefined(action.requiresFreshEvidence, defaultRequiresFreshEvidenceForAction(type)),
+    costUsd: firstDefined(action.costUsd, defaultCostUsdForAction(type)),
+    protectedTool: firstDefined(action.protectedTool, type === 'mcp_protected_tool'),
+    operatorApprovalRequired: firstDefined(action.operatorApprovalRequired, false),
+    guardrails: {
+      localDecisionOnly: true,
+      writesSolanaState: false,
+      usesKeypairs: false,
+      deploysPrograms: false,
+      publishesPackages: false,
+      livePaymentRequired: false,
+    },
+  };
+
+  if (action.evidenceLookup !== undefined) descriptor.evidenceLookup = action.evidenceLookup;
+  return descriptor;
+}
+
 function staleEvidenceDecision(action, options, reasonCodes, checks) {
   const lookup = action.evidenceLookup || null;
   if (!lookup || lookup.type !== 'x402') {
@@ -158,6 +302,7 @@ function normalizeAction(action = {}) {
   return {
     type: action.type || 'generic',
     resource: action.resource || null,
+    resourceLabel: action.resourceLabel || null,
     operation: action.operation || null,
     requiresCapability: action.requiresCapability || null,
     minimumTrustScore: Number.isFinite(action.minimumTrustScore) ? action.minimumTrustScore : null,
@@ -189,6 +334,149 @@ function clampScore(value) {
   return Math.max(0, Math.min(100, score));
 }
 
+function trustScoreBand(score) {
+  if (score >= 90) return '90-100';
+  if (score >= 80) return '80-89';
+  if (score >= 70) return '70-79';
+  if (score >= 50) return '50-69';
+  if (score >= 25) return '25-49';
+  return '0-24';
+}
+
+function sanitizeAuditChecks(checks = {}) {
+  const sanitized = { ...checks };
+  if (sanitized.evidenceLookup && typeof sanitized.evidenceLookup === 'object') {
+    sanitized.evidenceLookup = {
+      type: sanitized.evidenceLookup.type || null,
+      configured: true,
+      maxCostUsd: sanitized.evidenceLookup.maxCostUsd ?? null,
+    };
+  }
+  return sanitized;
+}
+
+function firstDefined(...values) {
+  return values.find((value) => value !== undefined);
+}
+
+function defaultResourceForAction(type, action) {
+  if (type === 'mcp_protected_tool') return 'mcp://protected/tool';
+  if (type === 'agentfolio_trust_gate') {
+    if (action.profileId) {
+      return `https://agentfolio.bot/api/profile/${encodeURIComponent(String(action.profileId))}/trust-score`;
+    }
+    return 'https://agentfolio.bot/api/profile/:id/trust-score';
+  }
+  if (type === 'x402_endpoint') return 'x402://paid-endpoint';
+  return null;
+}
+
+function defaultOperationForAction(type) {
+  if (type === 'mcp_protected_tool') return 'invoke';
+  if (type === 'agentfolio_trust_gate') return 'trust-score-read';
+  if (type === 'x402_endpoint') return 'lookup';
+  return null;
+}
+
+function defaultCapabilityForAction(type) {
+  if (type === 'agentfolio_trust_gate') return 'agentfolio:trust-read';
+  return null;
+}
+
+function defaultMinimumTrustScoreForAction(type) {
+  if (type === 'agentfolio_trust_gate') return DEFAULT_POLICY.minimumTrustScore;
+  return null;
+}
+
+function defaultAllowDegradedForAction(type) {
+  return type === 'agentfolio_trust_gate';
+}
+
+function defaultRequiresFreshEvidenceForAction(type) {
+  return type === 'mcp_protected_tool' || type === 'agentfolio_trust_gate';
+}
+
+function defaultCostUsdForAction(type) {
+  if (type === 'x402_endpoint') return 0;
+  return 0;
+}
+
+function normalizePolicy(policy) {
+  if (policy === undefined) return {};
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy)) {
+    throw new Error('runtime policy adapter policy must be an object');
+  }
+  return { ...policy };
+}
+
+function applyDefaultActionType(input, defaultActionType) {
+  if (!defaultActionType || typeof input === 'string') return input;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return input;
+  if (input.type || input.surface) return input;
+  return { type: defaultActionType, ...input };
+}
+
+function resolveAdapterNow(nowProvider, methodNow) {
+  if (methodNow !== undefined) return methodNow;
+  if (typeof nowProvider === 'function') return nowProvider();
+  return nowProvider;
+}
+
+function isValidDateInput(value) {
+  const date = new Date(value);
+  return !Number.isNaN(date.getTime());
+}
+
+function attachRedactedResourceLabel(actionDescriptor, redact) {
+  if (!actionDescriptor || typeof actionDescriptor !== 'object' || Array.isArray(actionDescriptor)) {
+    return actionDescriptor;
+  }
+  if (typeof actionDescriptor.resource !== 'string') return actionDescriptor;
+  const redacted = redact(actionDescriptor.resource);
+  return {
+    ...actionDescriptor,
+    resourceLabel: typeof redacted === 'string' ? redacted : '[redacted]',
+  };
+}
+
+function explainRuntimePolicyResult(result = {}) {
+  const reasonCodes = Array.isArray(result.reasonCodes) ? result.reasonCodes : [];
+  return reasonCodes.map((code) => RUNTIME_POLICY_EXPLANATIONS[code] || `Runtime policy returned ${code}.`);
+}
+
+const RUNTIME_POLICY_EXPLANATIONS = Object.freeze({
+  [REASON_CODES.ACTION_PAYMENT_NEEDS_APPROVAL]: 'The action cost exceeds the host auto-spend policy and needs approval.',
+  [REASON_CODES.ACTION_PAYMENT_PREAPPROVED]: 'The host preapproved payment for this action.',
+  [REASON_CODES.EVIDENCE_FRESH]: 'The identity evidence is fresh enough for this action.',
+  [REASON_CODES.EVIDENCE_STALE_OR_MISSING]: 'The identity evidence is stale or missing.',
+  [REASON_CODES.IDENTITY_INACTIVE]: 'The identity is inactive.',
+  [REASON_CODES.IDENTITY_UNVERIFIED]: 'The identity is not verified by the host policy.',
+  [REASON_CODES.INVALID_ACTION_COST_USD]: 'The action cost must be a finite non-negative number.',
+  [REASON_CODES.LOCAL_POLICY_ALLOW]: 'The local host policy allows the action.',
+  [REASON_CODES.MISSING_CAPABILITY]: 'The identity is missing the capability required by this action.',
+  [REASON_CODES.PROTECTED_TOOL_REQUIRES_APPROVAL]: 'The protected tool requires operator approval.',
+  [REASON_CODES.TRUST_SCORE_BELOW_DENY_FLOOR]: 'The trust score is below the host deny floor.',
+  [REASON_CODES.TRUST_SCORE_BELOW_MINIMUM]: 'The trust score is below the minimum for this action.',
+  [REASON_CODES.TRUST_SCORE_OK]: 'The trust score satisfies the local policy.',
+  [REASON_CODES.X402_LOOKUP_PAYMENT_PREAPPROVED]: 'The host preapproved payment for the x402 evidence lookup.',
+  [REASON_CODES.X402_LOOKUP_REQUIRES_APPROVAL]: 'The x402 evidence lookup requires payment approval.',
+  [REASON_CODES.X402_PAYMENT_IS_NOT_ACTION_AUTHORIZATION]: 'x402 payment does not authorize the agent action.',
+});
+
+function safeIsoDate(value) {
+  const date = value ? new Date(value) : new Date();
+  if (Number.isNaN(date.getTime())) return new Date().toISOString();
+  return date.toISOString();
+}
+
+function resourceKind(resource) {
+  if (!resource || typeof resource !== 'string') return null;
+  const schemeMatch = resource.match(/^([a-z][a-z0-9+.-]*):/i);
+  if (schemeMatch) return `${schemeMatch[1].toLowerCase()}:`;
+  if (resource.startsWith('/')) return 'path';
+  return 'opaque';
+}
+
 function isEvidenceFresh(identity, policy, now) {
   if (!identity.evidenceUpdatedAt) return false;
   const updatedAt = new Date(identity.evidenceUpdatedAt);
@@ -202,5 +490,10 @@ module.exports = {
   DECISIONS,
   DEFAULT_POLICY,
   REASON_CODES,
+  RUNTIME_POLICY_AUDIT_TRACE_SCHEMA_VERSION,
+  RUNTIME_POLICY_HOST_ACTION_DESCRIPTOR_SCHEMA_VERSION,
+  buildRuntimePolicyActionDescriptor,
+  buildRuntimePolicyAuditTrace,
+  createRuntimePolicyAdapter,
   evaluateRuntimePolicy,
 };

package/src/signer-policy.js

@@ -0,0 +1,210 @@
+'use strict';
+
+const { PublicKey } = require('@solana/web3.js');
+
+const SATP_SIGNER_ROLES = Object.freeze({
+  OPERATIONAL_SIGNER: 'operational_signer',
+  OWNER_UPGRADE_AUTHORITY: 'owner_upgrade_authority',
+});
+
+const OPERATIONAL_SIGNER_ALLOWED_ACTIONS = Object.freeze([
+  'devnet_fee_payment',
+  'devnet_transaction_submission',
+  'offline_transaction_preparation',
+  'read_only_rpc',
+]);
+
+const OWNER_UPGRADE_AUTHORITY_BLOCKED_ACTIONS = Object.freeze([
+  'program_upgrade',
+  'authority_transfer',
+  'key_generation',
+  'key_rotation',
+  'mainnet_deploy',
+  'devnet_deploy',
+  'npm_publish',
+  'funds_custody',
+  'funds_transfer',
+]);
+
+const OPERATIONAL_SIGNER_AUTHORITY_BOUNDARY =
+  'no_upgrade_authority_no_key_management_no_funds_custody';
+
+const OWNER_UPGRADE_AUTHORITY_CUSTODY = 'owner_held';
+
+const SECRET_FIELD_NAMES = Object.freeze([
+  'keypair',
+  'keypairPath',
+  'secretKey',
+  'privateKey',
+  'seedPhrase',
+  'mnemonic',
+  'rawEnv',
+]);
+
+function normalizePublicKey(value, fieldName) {
+  if (value === undefined || value === null || value === '') {
+    throw new Error(`${fieldName} is required`);
+  }
+  return new PublicKey(value).toBase58();
+}
+
+function assertNoSecretFields(input, path = 'config') {
+  if (!input || typeof input !== 'object') return;
+
+  for (const [key, value] of Object.entries(input)) {
+    const childPath = `${path}.${key}`;
+    if (SECRET_FIELD_NAMES.includes(key)) {
+      throw new Error(`${childPath} must not be present in SATP signer policy config`);
+    }
+    if (value && typeof value === 'object' && !Buffer.isBuffer(value) && !(value instanceof PublicKey)) {
+      assertNoSecretFields(value, childPath);
+    }
+  }
+}
+
+function normalizeOperationalActions(actions) {
+  const requested = actions === undefined ? OPERATIONAL_SIGNER_ALLOWED_ACTIONS : actions;
+  if (!Array.isArray(requested)) {
+    throw new Error('operational signer actions must be an array');
+  }
+
+  const seen = new Set();
+  for (const action of requested) {
+    if (typeof action !== 'string' || action.length === 0) {
+      throw new Error('operational signer actions must be non-empty strings');
+    }
+    if (!OPERATIONAL_SIGNER_ALLOWED_ACTIONS.includes(action)) {
+      throw new Error(`operational signer action is not low-privilege: ${action}`);
+    }
+    if (OWNER_UPGRADE_AUTHORITY_BLOCKED_ACTIONS.includes(action)) {
+      throw new Error(`operational signer action is owner-gated: ${action}`);
+    }
+    seen.add(action);
+  }
+
+  return Array.from(seen).sort();
+}
+
+function arraysMatchExactly(actual, expected) {
+  if (!Array.isArray(actual) || actual.length !== expected.length) {
+    return false;
+  }
+
+  const sortedActual = actual.slice().sort();
+  const sortedExpected = expected.slice().sort();
+  return sortedExpected.every((action, index) => sortedActual[index] === action);
+}
+
+function buildSignerSeparationConfig(opts = {}) {
+  assertNoSecretFields(opts);
+
+  const network = opts.network || 'devnet';
+  if (network !== 'devnet' && network !== 'mainnet') {
+    throw new Error('Invalid network: expected devnet or mainnet');
+  }
+
+  const operationalSigner = normalizePublicKey(
+    opts.operationalSignerPublicKey,
+    'operationalSignerPublicKey',
+  );
+  const ownerUpgradeAuthority = normalizePublicKey(
+    opts.ownerUpgradeAuthorityPublicKey,
+    'ownerUpgradeAuthorityPublicKey',
+  );
+
+  if (operationalSigner === ownerUpgradeAuthority) {
+    throw new Error('operational signer must be distinct from Owner upgrade authority');
+  }
+
+  return {
+    schemaVersion: 'satp.signerSeparation.v1',
+    network,
+    operationalSigner: {
+      role: SATP_SIGNER_ROLES.OPERATIONAL_SIGNER,
+      publicKey: operationalSigner,
+      allowedActions: normalizeOperationalActions(opts.operationalAllowedActions),
+      blockedActions: OWNER_UPGRADE_AUTHORITY_BLOCKED_ACTIONS.slice().sort(),
+      authorityBoundary: OPERATIONAL_SIGNER_AUTHORITY_BOUNDARY,
+    },
+    ownerUpgradeAuthority: {
+      role: SATP_SIGNER_ROLES.OWNER_UPGRADE_AUTHORITY,
+      publicKey: ownerUpgradeAuthority,
+      custody: OWNER_UPGRADE_AUTHORITY_CUSTODY,
+      operationalSignerMayUse: false,
+    },
+    flags: {
+      publicKeysOnly: true,
+      readsKeypairs: false,
+      generatesKeypairs: false,
+      transfersAuthority: false,
+      deploysPrograms: false,
+      publishesPackages: false,
+      writesSolanaState: false,
+    },
+  };
+}
+
+function validateSignerSeparationConfig(config) {
+  try {
+    assertNoSecretFields(config);
+    const normalized = buildSignerSeparationConfig({
+      network: config && config.network,
+      operationalSignerPublicKey: config && config.operationalSigner && config.operationalSigner.publicKey,
+      ownerUpgradeAuthorityPublicKey: config && config.ownerUpgradeAuthority && config.ownerUpgradeAuthority.publicKey,
+      operationalAllowedActions: config && config.operationalSigner && config.operationalSigner.allowedActions,
+    });
+
+    const errors = [];
+    if (!config || config.schemaVersion !== 'satp.signerSeparation.v1') {
+      errors.push('schemaVersion must be satp.signerSeparation.v1');
+    }
+    if (!config || !config.flags || config.flags.publicKeysOnly !== true) {
+      errors.push('flags.publicKeysOnly must be true');
+    }
+    if (!config || !config.operationalSigner || config.operationalSigner.role !== SATP_SIGNER_ROLES.OPERATIONAL_SIGNER) {
+      errors.push('operationalSigner.role must be operational_signer');
+    }
+    if (!config || !config.ownerUpgradeAuthority || config.ownerUpgradeAuthority.role !== SATP_SIGNER_ROLES.OWNER_UPGRADE_AUTHORITY) {
+      errors.push('ownerUpgradeAuthority.role must be owner_upgrade_authority');
+    }
+    if (!config || !config.operationalSigner || config.operationalSigner.authorityBoundary !== OPERATIONAL_SIGNER_AUTHORITY_BOUNDARY) {
+      errors.push(`operationalSigner.authorityBoundary must be ${OPERATIONAL_SIGNER_AUTHORITY_BOUNDARY}`);
+    }
+    if (!config || !config.ownerUpgradeAuthority || config.ownerUpgradeAuthority.custody !== OWNER_UPGRADE_AUTHORITY_CUSTODY) {
+      errors.push(`ownerUpgradeAuthority.custody must be ${OWNER_UPGRADE_AUTHORITY_CUSTODY}`);
+    }
+    if (
+      !config
+      || !config.operationalSigner
+      || !arraysMatchExactly(config.operationalSigner.blockedActions, OWNER_UPGRADE_AUTHORITY_BLOCKED_ACTIONS)
+    ) {
+      errors.push('operationalSigner.blockedActions must list all owner-gated actions');
+    }
+    if (config && config.ownerUpgradeAuthority && config.ownerUpgradeAuthority.operationalSignerMayUse !== false) {
+      errors.push('ownerUpgradeAuthority.operationalSignerMayUse must be false');
+    }
+    for (const flagName of [
+      'readsKeypairs',
+      'generatesKeypairs',
+      'transfersAuthority',
+      'deploysPrograms',
+      'publishesPackages',
+      'writesSolanaState',
+    ]) {
+      if (!config || !config.flags || config.flags[flagName] !== false) {
+        errors.push(`flags.${flagName} must be false`);
+      }
+    }
+    return { ok: errors.length === 0, errors, normalized };
+  } catch (e) {
+    return { ok: false, errors: [e.message], normalized: null };
+  }
+}
+
+module.exports = {
+  SATP_SIGNER_ROLES,
+  OPERATIONAL_SIGNER_ALLOWED_ACTIONS,
+  OWNER_UPGRADE_AUTHORITY_BLOCKED_ACTIONS,
+  buildSignerSeparationConfig,
+  validateSignerSeparationConfig,
+};

package/src/v3-idl-discriminators.js

@@ -0,0 +1,17 @@
+'use strict';
+
+// Generated by `node scripts/generate-v3-idls.mjs`; do not edit by hand.
+const V3_IDL_ACCOUNT_DISCRIMINATORS = Object.freeze({
+  "Attestation": Object.freeze([152, 125, 183, 86, 36, 146, 121, 73]),
+  "EscrowV3": Object.freeze([145, 108, 37, 52, 197, 162, 232, 59]),
+  "GenesisRecord": Object.freeze([22, 160, 245, 112, 178, 126, 177, 106]),
+  "LinkedWallet": Object.freeze([43, 44, 217, 238, 93, 127, 166, 59]),
+  "MintTracker": Object.freeze([217, 230, 22, 187, 250, 88, 11, 174]),
+  "NameRegistry": Object.freeze([169, 63, 83, 240, 198, 158, 53, 11]),
+  "Review": Object.freeze([124, 63, 203, 215, 226, 30, 222, 15]),
+  "ReviewCounter": Object.freeze([89, 31, 82, 96, 68, 42, 80, 60]),
+});
+
+module.exports = {
+  V3_IDL_ACCOUNT_DISCRIMINATORS,
+};

package/src/v3-pda.d.ts

@@ -11,6 +11,12 @@ export interface V3ProgramIds {
   ESCROW: PublicKey;
 }
 
+export const SPL_TOKEN_PROGRAM_ID: PublicKey;
+export const ASSOCIATED_TOKEN_PROGRAM_ID: PublicKey;
+export const V3_DEVNET_TOKEN_MINTS: {
+  USDC: PublicKey;
+};
+
 /** Get all V3 program IDs for a network. */
 export function getV3ProgramIds(network?: Network): V3ProgramIds;
 
@@ -70,3 +76,23 @@ export function getV3EscrowPDA(
   nonce: number | bigint,
   network?: Network
 ): [PublicKey, number];
+
+/** Derive canonical Associated Token Account address. */
+export function getAssociatedTokenAddress(
+  owner: PublicKey | string,
+  mint: PublicKey | string
+): [PublicKey, number];
+
+/** Derive Escrow V3 PDA plus its SPL vault ATA for a mint. */
+export function getV3EscrowVaultATA(
+  client: PublicKey | string,
+  descriptionHash: Buffer,
+  nonce: number | bigint,
+  mint: PublicKey | string,
+  network?: Network
+): {
+  escrowPDA: PublicKey;
+  escrowBump: number;
+  vaultATA: PublicKey;
+  vaultBump: number;
+};