auramaxx 0.0.1

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;
+}

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

@@ -0,0 +1,172 @@
+import { isIPv4, isIPv6 } from 'net';
+import {
+  AdvisoryFinding,
+  API_AUDIT_EXIT_CODES,
+  API_REGISTRY_ERROR_CODES,
+  API_REGISTRY_IDENTITY_REGEX,
+  API_REGISTRY_RESERVED_NAMESPACES,
+  API_REGISTRY_RESERVED_PACKAGE_NAMES,
+  LocalPolicy,
+  PublisherKey,
+  SignatureEnvelope,
+  permissionSchema,
+} from './contracts';
+
+export class ApiRegistryValidationError extends Error {
+  constructor(public readonly code: string, message: string) {
+    super(message);
+    this.name = 'ApiRegistryValidationError';
+  }
+}
+
+export function validatePackageIdentity(identity: string): { namespace: string; name: string } {
+  const match = identity.match(API_REGISTRY_IDENTITY_REGEX);
+  if (!match) {
+    throw new ApiRegistryValidationError(
+      API_REGISTRY_ERROR_CODES.nameInvalid,
+      `Invalid package identity "${identity}". Expected @namespace/name`
+    );
+  }
+
+  const namespace = match[1];
+  const name = match[2];
+
+  if (API_REGISTRY_RESERVED_NAMESPACES.has(namespace) || API_REGISTRY_RESERVED_PACKAGE_NAMES.has(name)) {
+    throw new ApiRegistryValidationError(
+      API_REGISTRY_ERROR_CODES.nameInvalid,
+      `Package identity "${identity}" uses a reserved namespace or package name`
+    );
+  }
+
+  return { namespace, name };
+}
+
+function isFqdn(host: string): boolean {
+  // strict enough for MVP: labels with lowercase letters/digits/hyphens, at least one dot
+  if (!host.includes('.')) return false;
+  if (host.includes('*') || host.includes('/') || host.includes('?') || host.includes(':')) return false;
+  const labels = host.split('.');
+  return labels.every((label) => /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(label));
+}
+
+export function validateAllowedHosts(allowedHosts: string[]): void {
+  for (const host of allowedHosts) {
+    if (!isFqdn(host) || isIPv4(host) || isIPv6(host)) {
+      throw new ApiRegistryValidationError(
+        API_REGISTRY_ERROR_CODES.egressDenied,
+        `Host "${host}" is invalid. allowedHosts must contain FQDN values only`
+      );
+    }
+  }
+}
+
+export function enforceEgressPolicy(hostname: string, allowedHosts: readonly string[]): void {
+  if (!allowedHosts.includes(hostname)) {
+    throw new ApiRegistryValidationError(
+      API_REGISTRY_ERROR_CODES.egressDenied,
+      `Blocked outbound host: ${hostname}`
+    );
+  }
+}
+
+export function validateSignatureEnvelope(envelope: SignatureEnvelope): void {
+  if (envelope.algorithm !== 'ed25519') {
+    throw new ApiRegistryValidationError(
+      API_REGISTRY_ERROR_CODES.signatureAlgorithmUnsupported,
+      `Unsupported signature algorithm: ${envelope.algorithm}`
+    );
+  }
+
+  if (!envelope.keyId || !envelope.sig || !envelope.payloadHash || !envelope.createdAt) {
+    throw new ApiRegistryValidationError(
+      API_REGISTRY_ERROR_CODES.signatureAlgorithmUnsupported,
+      'Signature envelope is missing required fields'
+    );
+  }
+}
+
+export function resolveEffectivePermissions(
+  requiredPermissions: string[],
+  localPolicy: LocalPolicy,
+  runtimeHardDeny: Set<string>
+): string[] {
+  for (const permission of requiredPermissions) {
+    const parsed = permissionSchema.safeParse(permission);
+    if (!parsed.success) {
+      throw new ApiRegistryValidationError(
+        API_REGISTRY_ERROR_CODES.permissionUnresolved,
+        `Required permission "${permission}" is invalid: ${parsed.error.issues.map((issue) => issue.message).join('; ')}`
+      );
+    }
+
+    const deniedByRuntime = runtimeHardDeny.has(permission);
+    const deniedByPolicy = (localPolicy.deny ?? []).includes(permission);
+    const allowedByPolicy = (localPolicy.allow ?? []).includes(permission);
+
+    if (deniedByRuntime || deniedByPolicy || !allowedByPolicy) {
+      throw new ApiRegistryValidationError(
+        API_REGISTRY_ERROR_CODES.permissionUnresolved,
+        `Required permission "${permission}" could not be resolved under local/runtime policy`
+      );
+    }
+  }
+
+  return [...new Set(requiredPermissions)].sort();
+}
+
+export function enforceHistoricalKeyTrust(key: PublisherKey, signatureCreatedAt: string): void {
+  const signatureTime = Date.parse(signatureCreatedAt);
+  const keyCreatedAt = Date.parse(key.createdAt);
+
+  if (Number.isNaN(signatureTime) || Number.isNaN(keyCreatedAt)) {
+    throw new ApiRegistryValidationError(
+      API_REGISTRY_ERROR_CODES.keyTrustInvalid,
+      'Invalid timestamp in key trust evaluation'
+    );
+  }
+
+  if (signatureTime < keyCreatedAt) {
+    throw new ApiRegistryValidationError(
+      API_REGISTRY_ERROR_CODES.keyTrustInvalid,
+      'Signature predates key creation'
+    );
+  }
+
+  if (key.status === 'compromised') {
+    const cutoff = Date.parse(key.compromiseDetectedAt ?? '');
+    if (Number.isNaN(cutoff) || signatureTime >= cutoff) {
+      throw new ApiRegistryValidationError(
+        API_REGISTRY_ERROR_CODES.keyTrustInvalid,
+        'Signature is outside historical trust window for compromised key'
+      );
+    }
+  }
+}
+
+export function evaluateAuditExitCode(input: {
+  mode: 'ci' | 'local';
+  yanked: boolean;
+  integrityFailure: boolean;
+  findings: AdvisoryFinding[];
+}): number {
+  if (input.integrityFailure) return API_AUDIT_EXIT_CODES.integrityFailure;
+  if (input.yanked) return API_AUDIT_EXIT_CODES.yankedBlocked;
+
+  const hasExploitKnown = input.findings.some((finding) => Boolean(finding.exploitKnown));
+  const hasCritical = input.findings.some((finding) => finding.severity === 'critical');
+  const hasHigh = input.findings.some((finding) => finding.severity === 'high');
+
+  if (hasExploitKnown || hasCritical) {
+    return API_AUDIT_EXIT_CODES.advisoryBlocked;
+  }
+
+  if (input.mode === 'ci' && hasHigh) {
+    return API_AUDIT_EXIT_CODES.advisoryBlocked;
+  }
+
+  if (input.mode === 'local' && hasHigh) {
+    return API_AUDIT_EXIT_CODES.warning;
+  }
+
+  return API_AUDIT_EXIT_CODES.ok;
+}

package/server/lib/apikey-migration.ts

@@ -0,0 +1,258 @@
+import { prisma } from './db';
+import { createCredential, deleteCredential, getCredential, listCredentials, readCredentialSecrets, updateCredential } from './credentials';
+import { getPrimaryVaultId, isVaultUnlocked, listVaults } from './cold';
+import { CredentialField, CredentialFile } from '../types';
+import { normalizeScope } from './credential-scope';
+
+const APIKEY_TYPE = 'apikey';
+export const APIKEY_DB_PLACEHOLDER = '__AURAMAXX_VAULT_ONLY__';
+
+let migrationInFlight: Promise<void> | null = null;
+let migrationSettled = false;
+
+export interface ApiKeyCredentialRecord {
+  id: string;
+  service: string;
+  name: string;
+  keyMasked: string;
+  metadata: unknown;
+  createdAt: string;
+  updatedAt: string;
+}
+
+function getActiveVaultId(): string | null {
+  const primary = getPrimaryVaultId();
+  if (primary && isVaultUnlocked(primary)) {
+    return primary;
+  }
+  const unlocked = listVaults().find(vault => vault.isUnlocked);
+  return unlocked?.id || null;
+}
+
+function parseMetadata(metadata: string | null): unknown {
+  if (!metadata) return null;
+  try {
+    return JSON.parse(metadata);
+  } catch {
+    return metadata;
+  }
+}
+
+export function maskKey(key: string): string {
+  if (key.length <= 8) {
+    return '*'.repeat(key.length);
+  }
+  return `${key.slice(0, 4)}${'*'.repeat(key.length - 8)}${key.slice(-4)}`;
+}
+
+function listApiKeyCredentialsRaw(): CredentialFile[] {
+  return listCredentials({ type: APIKEY_TYPE });
+}
+
+function findApiKeyCredential(service: string, name: string): CredentialFile | null {
+  const normalizedService = normalizeScope(service);
+  const normalizedName = normalizeScope(name);
+
+  for (const credential of listApiKeyCredentialsRaw()) {
+    const metaService = typeof credential.meta.service === 'string' ? normalizeScope(credential.meta.service) : '';
+    const metaName = typeof credential.meta.name === 'string' ? normalizeScope(credential.meta.name) : '';
+    if (metaService === normalizedService && metaName === normalizedName) {
+      return credential;
+    }
+  }
+
+  return null;
+}
+
+function findApiKeyCredentialsByService(service: string): CredentialFile[] {
+  const normalizedService = normalizeScope(service);
+  return listApiKeyCredentialsRaw().filter((credential) => {
+    const metaService = typeof credential.meta.service === 'string' ? normalizeScope(credential.meta.service) : '';
+    return metaService === normalizedService;
+  });
+}
+
+function toApiKeyRecord(credential: CredentialFile): ApiKeyCredentialRecord {
+  const service = typeof credential.meta.service === 'string' ? credential.meta.service : '';
+  const name = typeof credential.meta.name === 'string' ? credential.meta.name : credential.name;
+  const keyMasked = typeof credential.meta.keyMasked === 'string' ? credential.meta.keyMasked : '********';
+
+  return {
+    id: credential.id,
+    service,
+    name,
+    keyMasked,
+    metadata: credential.meta.metadata ?? null,
+    createdAt: credential.createdAt,
+    updatedAt: credential.updatedAt,
+  };
+}
+
+function buildApiKeyMeta(service: string, name: string, key: string, metadata: unknown): Record<string, unknown> {
+  return {
+    service,
+    name,
+    tags: [normalizeScope(service)],
+    keyMasked: maskKey(key),
+    metadata: metadata ?? null,
+  };
+}
+
+function apiKeySecretField(key: string): CredentialField[] {
+  return [{ key: 'key', value: key, type: 'secret', sensitive: true }];
+}
+
+function isLegacyPlaintextKey(value: string): boolean {
+  return value.trim().length > 0 && value !== APIKEY_DB_PLACEHOLDER;
+}
+
+export async function migrateApiKeysFromDatabase(): Promise<{
+  migrated: number;
+  skipped: number;
+  reason?: string;
+}> {
+  const rows = await prisma.apiKey.findMany({
+    where: { isActive: true },
+    orderBy: { createdAt: 'asc' },
+  });
+  if (rows.length === 0) {
+    return { migrated: 0, skipped: 0 };
+  }
+
+  const vaultId = getActiveVaultId();
+  if (!vaultId) {
+    return { migrated: 0, skipped: rows.length, reason: 'No unlocked vault available for credential migration' };
+  }
+
+  let migrated = 0;
+  let skipped = 0;
+  for (const row of rows) {
+    if (!isLegacyPlaintextKey(row.key)) {
+      skipped++;
+      continue;
+    }
+    const existing = findApiKeyCredential(row.service, row.name);
+    const meta = buildApiKeyMeta(row.service, row.name, row.key, parseMetadata(row.metadata));
+    if (existing) {
+      updateCredential(existing.id, {
+        meta,
+        sensitiveFields: apiKeySecretField(row.key),
+      });
+    } else {
+      createCredential(vaultId, APIKEY_TYPE, `${row.service}:${row.name}`, meta, apiKeySecretField(row.key));
+    }
+    await prisma.apiKey.update({
+      where: { id: row.id },
+      data: {
+        key: APIKEY_DB_PLACEHOLDER,
+        updatedAt: new Date(),
+      },
+    });
+    migrated++;
+  }
+
+  return { migrated, skipped };
+}
+
+export async function ensureApiKeysMigrated(): Promise<void> {
+  if (migrationSettled) return;
+  if (!migrationInFlight) {
+    migrationInFlight = (async () => {
+      const result = await migrateApiKeysFromDatabase();
+      if (!result.reason) {
+        migrationSettled = true;
+      }
+    })().finally(() => {
+      migrationInFlight = null;
+    });
+  }
+  await migrationInFlight;
+}
+
+export function listApiKeyCredentials(): ApiKeyCredentialRecord[] {
+  return listApiKeyCredentialsRaw().map(toApiKeyRecord);
+}
+
+export function upsertApiKeyCredential(
+  service: string,
+  name: string,
+  key: string,
+  metadata: unknown,
+): ApiKeyCredentialRecord {
+  const vaultId = getActiveVaultId();
+  if (!vaultId) {
+    throw new Error('No unlocked vault available for API key credential storage');
+  }
+
+  const existing = findApiKeyCredential(service, name);
+  const nextMeta = buildApiKeyMeta(service, name, key, metadata);
+
+  const credential = existing
+    ? updateCredential(existing.id, {
+      meta: nextMeta,
+      sensitiveFields: apiKeySecretField(key),
+    })
+    : createCredential(
+      vaultId,
+      APIKEY_TYPE,
+      `${service}:${name}`,
+      nextMeta,
+      apiKeySecretField(key),
+    );
+
+  return toApiKeyRecord(credential);
+}
+
+export function deleteApiKeyCredentialById(id: string): ApiKeyCredentialRecord | null {
+  const credential = getCredential(id);
+  if (!credential || credential.type !== APIKEY_TYPE) {
+    return null;
+  }
+  const record = toApiKeyRecord(credential);
+  deleteCredential(id);
+  return record;
+}
+
+export function deleteApiKeyCredentialByServiceName(service: string, name: string): ApiKeyCredentialRecord | null {
+  const credential = findApiKeyCredential(service, name);
+  if (!credential) {
+    return null;
+  }
+  const record = toApiKeyRecord(credential);
+  deleteCredential(credential.id);
+  return record;
+}
+
+export function readApiKeyValueByServiceName(service: string, name: string): string | null {
+  const credential = findApiKeyCredential(service, name);
+  if (!credential) return null;
+  try {
+    const fields = readCredentialSecrets(credential.id);
+    const keyField = fields.find(field => normalizeScope(field.key) === 'key');
+    return keyField?.value || null;
+  } catch {
+    return null;
+  }
+}
+
+export function readApiKeyValueByService(service: string): string | null {
+  const credentials = findApiKeyCredentialsByService(service);
+  if (credentials.length === 0) return null;
+
+  const preferred = credentials.find((credential) => {
+    const metaName = typeof credential.meta.name === 'string' ? normalizeScope(credential.meta.name) : '';
+    return metaName === 'default';
+  }) || credentials[0];
+
+  try {
+    const fields = readCredentialSecrets(preferred.id);
+    const keyField = fields.find(field => normalizeScope(field.key) === 'key');
+    return keyField?.value || null;
+  } catch {
+    return null;
+  }
+}
+
+export function hasActiveApiKeyCredential(service: string): boolean {
+  return findApiKeyCredentialsByService(service).length > 0;
+}