auramaxx 1.0.0-alpha.4

package/server/lib/agent-profiles.ts

@@ -0,0 +1,328 @@
+import { createHash } from 'crypto';
+import { expandPermissions } from './permissions';
+import type { AgentTokenPayload } from '../types';
+import { normalizeScope } from './credential-scope';
+
+export type AgentProfileId =
+  | 'strict'
+  | 'dev'
+  | 'admin'
+  | 'observer'
+  | 'deploy-bot'
+  | 'rotation-bot'
+  | 'trader';
+
+export const LOCAL_AGENT_PROFILE_MODES = ['strict', 'dev', 'admin'] as const;
+export type LocalAgentProfileMode = typeof LOCAL_AGENT_PROFILE_MODES[number];
+
+export interface AgentPolicyProfileV1 {
+  id: AgentProfileId;
+  version: 'v1';
+  displayName: string;
+  description: string;
+  rationale: string;
+  permissions: string[];
+  credentialAccess: {
+    readScopes: string[];
+    writeScopes: string[];
+    excludeFields: string[];
+    maxReads?: number;
+  };
+  tokenDefaults: {
+    ttlSeconds: number;
+    maxReads?: number;
+  };
+  warnings: string[];
+}
+
+export interface ResolveProfileInput {
+  profileId: string;
+  profileVersion?: string;
+  overrides?: {
+    ttlSeconds?: number;
+    maxReads?: number;
+    readScopes?: string[];
+    writeScopes?: string[];
+    excludeFields?: string[];
+  };
+}
+
+export interface ResolvedProfilePolicy {
+  profile: {
+    id: AgentProfileId;
+    version: 'v1';
+    displayName: string;
+    rationale: string;
+  };
+  permissions: string[];
+  ttlSeconds: number;
+  credentialAccess: NonNullable<AgentTokenPayload['credentialAccess']>;
+  warnings: string[];
+  overrideDelta: string[];
+  effectivePolicyHash: string;
+}
+
+export class AgentProfileError extends Error {
+  code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'AgentProfileError';
+    this.code = code;
+  }
+}
+
+const BUILTIN_PROFILES: AgentPolicyProfileV1[] = [
+  {
+    id: 'strict',
+    version: 'v1',
+    displayName: 'Strict',
+    description: 'Manual-approval-first baseline profile for local agents.',
+    rationale: 'Use when you want every agent token request reviewed by a human.',
+    permissions: ['secret:read'],
+    credentialAccess: {
+      readScopes: ['vault:*'],
+      writeScopes: [],
+      excludeFields: ['password', 'cvv', 'privateKey', 'seedPhrase', 'refresh_token'],
+      maxReads: 50,
+    },
+    tokenDefaults: { ttlSeconds: 900, maxReads: 50 },
+    warnings: ['Pair with trust.localAutoApprove=false for strict local approval flow.'],
+  },
+  {
+    id: 'dev',
+    version: 'v1',
+    displayName: 'Dev',
+    description: 'Developer profile for local agent automation with non-financial scope.',
+    rationale: 'Use for day-to-day local dev workflows without granting financial operations.',
+    permissions: ['wallet:list', 'secret:read', 'secret:write', 'action:create', 'action:read', 'action:resolve'],
+    credentialAccess: {
+      readScopes: ['vault:*'],
+      writeScopes: ['vault:*'],
+      excludeFields: ['cvv', 'seedPhrase', 'privateKey', 'refresh_token'],
+      maxReads: 500,
+    },
+    tokenDefaults: { ttlSeconds: 3600, maxReads: 500 },
+    warnings: ['Includes secret:write. Prefer dedicated non-primary vaults for agent-managed credentials.'],
+  },
+  {
+    id: 'admin',
+    version: 'v1',
+    displayName: 'Admin',
+    description: 'Full-access local agent profile.',
+    rationale: 'Use only when you explicitly trust the local agent process with broad access.',
+    permissions: ['admin:*'],
+    credentialAccess: {
+      readScopes: ['*'],
+      writeScopes: ['*'],
+      excludeFields: [],
+    },
+    tokenDefaults: { ttlSeconds: 3600 },
+    warnings: ['Dangerous profile: grants admin:* (full access). Not recommended for primary vault workflows.'],
+  },
+  {
+    id: 'observer',
+    version: 'v1',
+    displayName: 'Observer',
+    description: 'Read-only observer with strong field redaction defaults.',
+    rationale: 'Use for diagnostics and reporting agents that should not mutate secrets.',
+    permissions: ['secret:read'],
+    credentialAccess: {
+      readScopes: ['vault:*'],
+      writeScopes: [],
+      excludeFields: ['password', 'cvv', 'privateKey', 'seedPhrase', 'refresh_token'],
+      maxReads: 500,
+    },
+    tokenDefaults: { ttlSeconds: 7200, maxReads: 500 },
+    warnings: ['Read-only profile. Sensitive fields are redacted by default.'],
+  },
+  {
+    id: 'deploy-bot',
+    version: 'v1',
+    displayName: 'Deploy Bot',
+    description: 'Project-scoped read profile for runtime/deploy credentials.',
+    rationale: 'Use for CI/CD agents that only need narrow secret reads.',
+    permissions: ['secret:read'],
+    credentialAccess: {
+      readScopes: ['tag:deploy', 'tag:runtime'],
+      writeScopes: [],
+      excludeFields: ['cvv', 'seedPhrase', 'privateKey'],
+      maxReads: 200,
+    },
+    tokenDefaults: { ttlSeconds: 3600, maxReads: 200 },
+    warnings: ['Ensure deployment credentials are tagged explicitly.'],
+  },
+  {
+    id: 'rotation-bot',
+    version: 'v1',
+    displayName: 'Rotation Bot',
+    description: 'Secret rotation profile with constrained read/write selectors.',
+    rationale: 'Use for automated credential rotation where write access is required.',
+    permissions: ['secret:read', 'secret:write'],
+    credentialAccess: {
+      readScopes: ['tag:rotation'],
+      writeScopes: ['tag:rotation'],
+      excludeFields: ['seedPhrase'],
+      maxReads: 100,
+    },
+    tokenDefaults: { ttlSeconds: 1800, maxReads: 100 },
+    warnings: ['Includes secret:write. Restrict scope tags to explicit rotation inventory.'],
+  },
+  {
+    id: 'trader',
+    version: 'v1',
+    displayName: 'Trader',
+    description: 'Trading profile with trade permissions plus scoped secret read.',
+    rationale: 'Use for trading automation with explicit risk review.',
+    permissions: ['trade:all', 'secret:read'],
+    credentialAccess: {
+      readScopes: ['tag:trading', 'tag:exchange'],
+      writeScopes: [],
+      excludeFields: ['seedPhrase', 'privateKey'],
+      maxReads: 300,
+    },
+    tokenDefaults: { ttlSeconds: 1200, maxReads: 300 },
+    warnings: ['High-risk profile: includes trading permissions. Verify wallet limits separately.'],
+  },
+];
+
+export function listProfiles(): AgentPolicyProfileV1[] {
+  return BUILTIN_PROFILES.map((p) => ({ ...p }));
+}
+
+export function getProfile(id: string, version: string = 'v1'): AgentPolicyProfileV1 {
+  const anyVersion = BUILTIN_PROFILES.find((p) => p.id === id);
+  if (!anyVersion) {
+    throw new AgentProfileError('AGENT_PROFILE_NOT_FOUND', `Unknown profile: ${id}@${version}`);
+  }
+  const profile = BUILTIN_PROFILES.find((p) => p.id === id && p.version === version);
+  if (!profile) {
+    throw new AgentProfileError('AGENT_PROFILE_VERSION_UNSUPPORTED', `Unsupported profile version: ${id}@${version}`);
+  }
+  return profile;
+}
+
+function canonicalScopes(scopes: string[] | undefined): string[] {
+  const normalized = (scopes || []).map(normalizeScope);
+  if (normalized.some((scope) => scope.includes('**') || scope.includes('(') || scope.includes(')'))) {
+    throw new AgentProfileError('AGENT_PROFILE_SCOPE_INVALID', 'Scope selectors contain unsupported wildcard/pattern syntax');
+  }
+  return Array.from(new Set(normalized)).sort();
+}
+
+function canonicalStringList(values: string[] | undefined): string[] {
+  return Array.from(new Set((values || []).map((v) => v.trim()).filter(Boolean))).sort();
+}
+
+function hashPolicy(policy: Omit<ResolvedProfilePolicy, 'effectivePolicyHash'>): string {
+  const stable = JSON.stringify({
+    permissions: Array.from(new Set(policy.permissions)).sort(),
+    credentialAccess: {
+      read: Array.from(new Set(policy.credentialAccess.read || [])).sort(),
+      write: Array.from(new Set(policy.credentialAccess.write || [])).sort(),
+      excludeFields: Array.from(new Set(policy.credentialAccess.excludeFields || [])).sort(),
+      maxReads: typeof policy.credentialAccess.maxReads === 'number' ? policy.credentialAccess.maxReads : null,
+    },
+    ttlSeconds: policy.ttlSeconds,
+    maxReads: typeof policy.credentialAccess.maxReads === 'number' ? policy.credentialAccess.maxReads : null,
+    rateBudget: {
+      state: 'none',
+      requests: null,
+      windowSeconds: null,
+      source: 'none',
+    },
+  });
+  return createHash('sha256').update(stable).digest('hex');
+}
+
+export function resolveProfileToEffectivePolicy(input: ResolveProfileInput): ResolvedProfilePolicy {
+  const profile = getProfile(input.profileId, input.profileVersion || 'v1');
+  const overrides = input.overrides || {};
+
+  const profileReadScopes = canonicalScopes(profile.credentialAccess.readScopes);
+  const profileWriteScopes = canonicalScopes(profile.credentialAccess.writeScopes);
+  const profileExclude = canonicalStringList(profile.credentialAccess.excludeFields);
+
+  const overrideDelta: string[] = [];
+
+  let ttlSeconds = profile.tokenDefaults.ttlSeconds;
+  if (overrides.ttlSeconds !== undefined) {
+    if (overrides.ttlSeconds <= 0 || overrides.ttlSeconds > ttlSeconds) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'ttlSeconds override must be positive and tighten-only');
+    }
+    ttlSeconds = overrides.ttlSeconds;
+    overrideDelta.push('ttlSeconds');
+  }
+
+  let maxReads = profile.credentialAccess.maxReads ?? profile.tokenDefaults.maxReads;
+  if (overrides.maxReads !== undefined) {
+    if (overrides.maxReads <= 0 || (typeof maxReads === 'number' && overrides.maxReads > maxReads)) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'maxReads override must be positive and tighten-only');
+    }
+    maxReads = overrides.maxReads;
+    overrideDelta.push('maxReads');
+  }
+
+  const readScopes = overrides.readScopes ? canonicalScopes(overrides.readScopes) : profileReadScopes;
+  const writeScopes = overrides.writeScopes ? canonicalScopes(overrides.writeScopes) : profileWriteScopes;
+
+  if (overrides.readScopes) {
+    if (!readScopes.every((scope) => profileReadScopes.includes(scope))) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'readScopes override cannot broaden profile scope');
+    }
+    overrideDelta.push('readScopes');
+  }
+
+  if (overrides.writeScopes) {
+    if (!writeScopes.every((scope) => profileWriteScopes.includes(scope))) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'writeScopes override cannot broaden profile scope');
+    }
+    overrideDelta.push('writeScopes');
+  }
+
+  if (readScopes.length === 0 && writeScopes.length === 0) {
+    throw new AgentProfileError('AGENT_PROFILE_SCOPE_EMPTY', 'Resolved profile selectors are empty');
+  }
+
+  const excludeFields = overrides.excludeFields ? canonicalStringList(overrides.excludeFields) : profileExclude;
+  if (overrides.excludeFields) {
+    const attemptedRemoval = profileExclude.some((field) => !excludeFields.includes(field));
+    if (attemptedRemoval) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'excludeFields override cannot remove profile-required exclusions');
+    }
+    overrideDelta.push('excludeFields');
+  }
+
+  const resolvedBase: Omit<ResolvedProfilePolicy, 'effectivePolicyHash'> = {
+    profile: {
+      id: profile.id,
+      version: profile.version,
+      displayName: profile.displayName,
+      rationale: profile.rationale,
+    },
+    permissions: Array.from(new Set(expandPermissions(profile.permissions))).sort(),
+    ttlSeconds,
+    credentialAccess: {
+      read: readScopes,
+      write: writeScopes,
+      excludeFields,
+      ...(typeof maxReads === 'number' ? { maxReads } : {}),
+    },
+    warnings: [...profile.warnings],
+    overrideDelta: Array.from(new Set(overrideDelta)).sort(),
+  };
+
+  return {
+    ...resolvedBase,
+    effectivePolicyHash: hashPolicy(resolvedBase),
+  };
+}
+
+export function summarizeEffectivePolicy(policy: ResolvedProfilePolicy): string {
+  return [
+    `${policy.profile.id}@${policy.profile.version}`,
+    `permissions=${policy.permissions.join(',')}`,
+    `ttl=${policy.ttlSeconds}s`,
+    `read=${(policy.credentialAccess.read || []).join(',') || 'none'}`,
+    `write=${(policy.credentialAccess.write || []).join(',') || 'none'}`,
+  ].join(' | ');
+}

package/server/lib/ai.ts

@@ -0,0 +1,285 @@
+/**
+ * AI Client Module
+ * ================
+ * Multi-provider AI abstraction supporting:
+ *   - Claude CLI (subscription/OAuth via `claude` binary)
+ *   - Claude API (direct Anthropic SDK with API key)
+ *   - Codex CLI (OpenAI's `codex` binary)
+ *   - OpenAI API (direct OpenAI SDK with API key)
+ *
+ * Provider selection read from system defaults (ai.provider); model auto-derived per provider.
+ * Extracted from strategy/hooks.ts so it's reusable beyond strategies.
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+import OpenAI from 'openai';
+import { execFile } from 'child_process';
+import { prisma } from './db';
+import { getDefault, onDefaultChanged } from './defaults';
+
+// ─── Types ─────────────────────────────────────────────────────────
+
+export type AiProviderMode = 'claude-cli' | 'claude-api' | 'codex-cli' | 'openai-api';
+
+export type ModelTier = 'fast' | 'standard' | 'powerful';
+
+export interface ProviderStatus {
+  mode: AiProviderMode;
+  label: string;
+  available: boolean;
+  reason: string;
+  models: string[];
+}
+
+// ─── Model Maps ────────────────────────────────────────────────────
+
+/** Claude model short names → full SDK model IDs */
+const MODEL_MAP: Record<string, string> = {
+  haiku: 'claude-haiku-4-5-20251001',
+  sonnet: 'claude-sonnet-4-5-20250929',
+  opus: 'claude-opus-4-6',
+};
+
+/** Codex/OpenAI model short names → full SDK model IDs */
+const CODEX_MODEL_MAP: Record<string, string> = {
+  'codex-mini': 'gpt-5.1-codex-mini',
+  'codex': 'gpt-5.3-codex',
+  'codex-max': 'gpt-5.1-codex-max',
+};
+
+/** Available models per provider */
+export const PROVIDER_MODELS: Record<AiProviderMode, string[]> = {
+  'claude-cli': ['haiku', 'sonnet', 'opus'],
+  'claude-api': ['haiku', 'sonnet', 'opus'],
+  'codex-cli': ['codex-mini', 'codex', 'codex-max'],
+  'openai-api': ['codex-mini', 'codex', 'codex-max'],
+};
+
+/** Model tiers per provider — fast/standard/powerful mapped to model short names */
+export const MODEL_TIERS: Record<AiProviderMode, Record<ModelTier, string>> = {
+  'claude-cli':  { fast: 'haiku', standard: 'sonnet', powerful: 'opus' },
+  'claude-api':  { fast: 'haiku', standard: 'sonnet', powerful: 'opus' },
+  'codex-cli':   { fast: 'codex-mini', standard: 'codex', powerful: 'codex-max' },
+  'openai-api':  { fast: 'codex-mini', standard: 'codex', powerful: 'codex-max' },
+};
+
+/** Permissions that trigger the 'powerful' tier (financial operations) */
+const POWERFUL_PERMISSIONS = new Set(['swap', 'send:hot', 'send:temp', 'fund', 'launch', 'admin:*']);
+
+/** Permissions that trigger the 'standard' tier (write operations) */
+const STANDARD_PERMISSIONS = new Set(['wallet:create:hot', 'wallet:create:temp']);
+
+/**
+ * Select a model tier based on hook name and token permissions.
+ * - init/shutdown → fast (lightweight lifecycle hooks)
+ * - Financial or admin permissions → powerful
+ * - Write permissions → standard
+ * - No token or read-only → fast
+ */
+export function selectModelTier(hookName: string, permissions: string[]): ModelTier {
+  // Lifecycle hooks always use fast tier
+  if (hookName === 'init' || hookName === 'shutdown') return 'fast';
+
+  // Check for powerful-tier permissions
+  for (const perm of permissions) {
+    if (POWERFUL_PERMISSIONS.has(perm)) return 'powerful';
+  }
+
+  // Check for standard-tier permissions
+  for (const perm of permissions) {
+    if (STANDARD_PERMISSIONS.has(perm)) return 'standard';
+  }
+
+  // No token or read-only permissions
+  return 'fast';
+}
+
+// ─── Cached Clients ────────────────────────────────────────────────
+
+let cachedAnthropicClient: Anthropic | null = null;
+let cachedOpenAiClient: OpenAI | null = null;
+
+/** @internal Reset cached clients (for testing only) */
+export function __resetCachedClient() {
+  cachedAnthropicClient = null;
+  cachedOpenAiClient = null;
+}
+
+// Reset cached clients when provider changes
+onDefaultChanged('ai.provider', () => {
+  cachedAnthropicClient = null;
+  cachedOpenAiClient = null;
+});
+
+// ─── Provider & Model Selection ────────────────────────────────────
+
+/**
+ * Get the active AI provider mode from system defaults.
+ */
+export async function getProviderMode(): Promise<AiProviderMode> {
+  return getDefault<AiProviderMode>('ai.provider', 'claude-cli');
+}
+
+/**
+ * Get the system-wide default model (standard tier), derived from the active provider.
+ */
+export async function getDefaultModel(): Promise<string> {
+  const provider = await getProviderMode();
+  return MODEL_TIERS[provider].standard;
+}
+
+/**
+ * Resolve a model short name to the full SDK model ID based on provider.
+ * CLI modes return the short name directly (CLIs handle them natively).
+ * API modes map to full model IDs.
+ */
+export function resolveModelId(name: string, provider: AiProviderMode): string {
+  switch (provider) {
+    case 'claude-cli':
+      return name; // Claude CLI handles short names natively
+    case 'claude-api':
+      return MODEL_MAP[name] || name;
+    case 'codex-cli':
+      return name; // Codex CLI handles short names natively
+    case 'openai-api':
+      return CODEX_MODEL_MAP[name] || name;
+    default:
+      return name;
+  }
+}
+
+// ─── SDK Clients ───────────────────────────────────────────────────
+
+/**
+ * Get an Anthropic SDK client (for claude-api mode).
+ * Priority: ANTHROPIC_API_KEY env → DB ApiKey (service: 'anthropic').
+ */
+export async function getAnthropicClient(): Promise<Anthropic> {
+  if (cachedAnthropicClient) return cachedAnthropicClient;
+
+  if (process.env.ANTHROPIC_API_KEY) {
+    cachedAnthropicClient = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+    return cachedAnthropicClient;
+  }
+
+  const apiKeyRow = await prisma.apiKey.findFirst({
+    where: { service: 'anthropic', isActive: true },
+  });
+  if (apiKeyRow) {
+    cachedAnthropicClient = new Anthropic({ apiKey: apiKeyRow.key });
+    return cachedAnthropicClient;
+  }
+
+  throw new Error(
+    'No Anthropic credentials found. Add an API key via Settings, set ANTHROPIC_API_KEY, or use Claude CLI mode (subscription).'
+  );
+}
+
+/**
+ * Get an OpenAI SDK client (for openai-api mode).
+ * Priority: OPENAI_API_KEY env → DB ApiKey (service: 'openai').
+ */
+export async function getOpenAiClient(): Promise<OpenAI> {
+  if (cachedOpenAiClient) return cachedOpenAiClient;
+
+  if (process.env.OPENAI_API_KEY) {
+    cachedOpenAiClient = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+    return cachedOpenAiClient;
+  }
+
+  const apiKeyRow = await prisma.apiKey.findFirst({
+    where: { service: 'openai', isActive: true },
+  });
+  if (apiKeyRow) {
+    cachedOpenAiClient = new OpenAI({ apiKey: apiKeyRow.key });
+    return cachedOpenAiClient;
+  }
+
+  throw new Error(
+    'No OpenAI credentials found. Add an API key via Settings or set OPENAI_API_KEY.'
+  );
+}
+
+// ─── Provider Status ───────────────────────────────────────────────
+
+/** Check if a CLI binary is available in PATH */
+function checkCliAvailable(binary: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    execFile('which', [binary], (err) => {
+      resolve(!err);
+    });
+  });
+}
+
+/** Check if an API key exists for a service (env or DB) */
+async function hasApiKey(service: string, envVar: string): Promise<boolean> {
+  if (process.env[envVar]) return true;
+  const row = await prisma.apiKey.findFirst({
+    where: { service, isActive: true },
+  });
+  return !!row;
+}
+
+/**
+ * Get availability status for each provider.
+ * Used by the dashboard UI to show status indicators.
+ */
+export async function getProviderStatus(): Promise<ProviderStatus[]> {
+  const [claudeCliOk, codexCliOk, anthropicKeyOk, openaiKeyOk] = await Promise.all([
+    checkCliAvailable('claude'),
+    checkCliAvailable('codex'),
+    hasApiKey('anthropic', 'ANTHROPIC_API_KEY'),
+    hasApiKey('openai', 'OPENAI_API_KEY'),
+  ]);
+
+  return [
+    {
+      mode: 'claude-cli',
+      label: 'Claude Max (CLI)',
+      available: claudeCliOk,
+      reason: claudeCliOk ? 'claude CLI found in PATH' : 'claude CLI not found in PATH',
+      models: PROVIDER_MODELS['claude-cli'],
+    },
+    {
+      mode: 'claude-api',
+      label: 'Claude API Key',
+      available: anthropicKeyOk,
+      reason: anthropicKeyOk ? 'Anthropic API key configured' : 'No Anthropic API key configured',
+      models: PROVIDER_MODELS['claude-api'],
+    },
+    {
+      mode: 'codex-cli',
+      label: 'Codex Max (CLI)',
+      available: codexCliOk,
+      reason: codexCliOk ? 'codex CLI found in PATH' : 'codex CLI not found in PATH',
+      models: PROVIDER_MODELS['codex-cli'],
+    },
+    {
+      mode: 'openai-api',
+      label: 'OpenAI API Key',
+      available: openaiKeyOk,
+      reason: openaiKeyOk ? 'OpenAI API key configured' : 'No OpenAI API key configured',
+      models: PROVIDER_MODELS['openai-api'],
+    },
+  ];
+}
+
+// ─── Backward Compatibility ────────────────────────────────────────
+
+/**
+ * @deprecated Use getProviderMode() instead.
+ * Kept temporarily for backward compatibility.
+ */
+export async function shouldUseCli(): Promise<boolean> {
+  const mode = await getProviderMode();
+  return mode === 'claude-cli' || mode === 'codex-cli';
+}
+
+/**
+ * @deprecated Use getProviderMode() instead.
+ * Returns 'sdk' if provider uses direct API, 'cli' otherwise.
+ */
+export async function getAiProvider(): Promise<'sdk' | 'cli'> {
+  const mode = await getProviderMode();
+  return (mode === 'claude-api' || mode === 'openai-api') ? 'sdk' : 'cli';
+}

package/server/lib/api-registry/contracts.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+
+export const API_REGISTRY_ERROR_CODES = {
+  nameInvalid: 'E_NAME_INVALID',
+  egressDenied: 'E_EGRESS_DENIED',
+  signatureAlgorithmUnsupported: 'E_SIG_ALG_UNSUPPORTED',
+  permissionUnresolved: 'E_PERMISSION_UNRESOLVED',
+  keyTrustInvalid: 'E_KEY_TRUST_INVALID',
+} as const;
+
+export const API_REGISTRY_RESERVED_NAMESPACES = new Set([
+  'aura',
+  'registry',
+  'security',
+  'system',
+  'admin',
+  'root',
+]);
+
+export const API_REGISTRY_RESERVED_PACKAGE_NAMES = new Set([
+  'internal',
+  'private',
+  'null',
+  'undefined',
+  'latest',
+]);
+
+export const API_REGISTRY_IDENTITY_REGEX =
+  /^@([a-z0-9][a-z0-9-]{1,38}[a-z0-9])\/([a-z0-9][a-z0-9-]{1,62}[a-z0-9])$/;
+
+export const API_REGISTRY_ALLOWED_PERMISSIONS = [
+  'http.read',
+  'http.write',
+  'events.emit',
+  'filesystem.read:workspace',
+  'filesystem.write:workspace',
+] as const;
+
+const scopedPermissionPattern = /^(secrets\.(read|write):[a-z0-9][a-z0-9:_-]{0,63})$/;
+
+export const permissionSchema = z
+  .string()
+  .refine((value) => API_REGISTRY_ALLOWED_PERMISSIONS.includes(value as (typeof API_REGISTRY_ALLOWED_PERMISSIONS)[number]) || scopedPermissionPattern.test(value), {
+    message: 'Permission is outside of the MVP bounded permission catalog',
+  })
+  .refine((value) => !value.includes('*'), {
+    message: 'Wildcard permissions are not permitted in MVP',
+  });
+
+export type KeyStatus = 'active' | 'retired' | 'compromised';
+
+export interface PublisherKey {
+  keyId: string;
+  status: KeyStatus;
+  createdAt: string;
+  compromiseDetectedAt?: string;
+}
+
+export interface SignatureEnvelope {
+  algorithm: string;
+  keyId: string;
+  sig: string;
+  createdAt: string;
+  payloadHash: string;
+}
+
+export interface LocalPolicy {
+  allow?: string[];
+  deny?: string[];
+}
+
+export const API_AUDIT_EXIT_CODES = {
+  ok: 0,
+  warning: 20,
+  advisoryBlocked: 21,
+  yankedBlocked: 22,
+  integrityFailure: 23,
+} as const;
+
+export type AdvisorySeverity = 'low' | 'medium' | 'high' | 'critical';
+export type AuditMode = 'ci' | 'local';
+
+export interface AdvisoryFinding {
+  severity: AdvisorySeverity;
+  exploitKnown?: boolean;
+}