feat(oci): add OCI manifest adapter for AI Card spec alignment (#1366) (#1456)

Implement OciManifestAdapter for converting AGT agent manifests to/from
OCI manifest format with AI Card compatibility. Enables registry-based
discovery and verification of agent metadata.

Features:
- AGT identity to AI Card conversion (bidirectional)
- OCI manifest packaging with typed layers (AI Card + policy)
- Layer digest verification (SHA-256)
- Policy rule packaging in OCI layers
- Standard OCI annotations (title, vendor, description)
- AI Card metadata preservation (DID, delegation, expiry)

Media types:
- application/vnd.ai-card.agent.v1+json (agent metadata)
- application/vnd.agt.policy.v1+json (governance policy)

New types: OciManifest, OciDescriptor, AICard, AICardSkill,
AICardCapabilities, AICardInvocation, OciPackageResult

20 tests covering conversion, packaging, unpacking, round-trips,
and integrity verification.

Closes #1366

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: imran-siddique

agent-governance-typescript/src/index.ts

@@ -28,6 +28,7 @@ export { GovernanceVerifier } from './verify';
 export { SurfaceParityChecker } from './surface-parity';
 export { CascadeContainmentManager } from './cascade-containment';
 export { ContextPoisoningDetector } from './context-poisoning';
+export { OciManifestAdapter } from './oci-manifest';
 
 // E2E Encryption (AgentMesh Wire Protocol v1.0)
 export {
@@ -92,6 +93,13 @@ export type {
   PoisoningFinding,
   ContextPoisoningScanResult,
   ContextIsolationViolation,
+  OciManifest,
+  OciDescriptor,
+  AICard,
+  AICardSkill,
+  AICardCapabilities,
+  AICardInvocation,
+  OciPackageResult,
 } from './types';
 export type { PromptDefenseConfig, PromptDefenseFinding, PromptDefenseReport } from './prompt-defense';
 export type {

agent-governance-typescript/src/oci-manifest.ts

@@ -0,0 +1,224 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+import { createHash } from 'crypto';
+import type {
+  AgentIdentityJSON,
+  AICard,
+  AICardCapabilities,
+  AICardSkill,
+  OciDescriptor,
+  OciManifest,
+  OciPackageResult,
+  PolicyRule,
+} from './types';
+
+const AI_CARD_MEDIA_TYPE = 'application/vnd.ai-card.agent.v1+json';
+const POLICY_MEDIA_TYPE = 'application/vnd.agt.policy.v1+json';
+const OCI_MANIFEST_MEDIA_TYPE = 'application/vnd.oci.image.manifest.v2+json';
+const OCI_CONFIG_MEDIA_TYPE = 'application/vnd.oci.image.config.v1+json';
+
+/**
+ * Converts AGT agent manifests to/from OCI manifest format with AI Card
+ * compatibility. Enables registry-based discovery and verification of
+ * agent metadata.
+ */
+export class OciManifestAdapter {
+  /**
+   * Convert an AGT agent identity to an AI Card.
+   */
+  identityToAICard(identity: AgentIdentityJSON, extra?: Partial<AICard>): AICard {
+    const card: AICard = {
+      name: identity.name ?? identity.did,
+      version: '1.0.0',
+      description: identity.description,
+      author: identity.organization ?? identity.sponsor,
+      capabilities: this.capabilitiesToAICard(identity.capabilities),
+      metadata: {
+        did: identity.did,
+        status: identity.status ?? 'active',
+        createdAt: identity.createdAt,
+        expiresAt: identity.expiresAt,
+        parentDid: identity.parentDid,
+        delegationDepth: identity.delegationDepth,
+      },
+      ...extra,
+    };
+
+    return card;
+  }
+
+  /**
+   * Convert an AI Card back to an AGT agent identity.
+   */
+  aiCardToIdentity(card: AICard, publicKey: string): AgentIdentityJSON {
+    const metadata = (card.metadata ?? {}) as Record<string, unknown>;
+    return {
+      did: (metadata.did as string) ?? `did:agent:${card.name}`,
+      publicKey,
+      capabilities: this.aiCardToCapabilities(card.capabilities),
+      name: card.name,
+      description: card.description,
+      organization: card.author,
+      status: (metadata.status as AgentIdentityJSON['status']) ?? 'active',
+      createdAt: metadata.createdAt as string | undefined,
+      expiresAt: metadata.expiresAt as string | undefined,
+      parentDid: metadata.parentDid as string | undefined,
+      delegationDepth: metadata.delegationDepth as number | undefined,
+    };
+  }
+
+  /**
+   * Package an agent identity and optional policy rules into an OCI manifest.
+   */
+  package(
+    identity: AgentIdentityJSON,
+    policyRules?: PolicyRule[],
+    extra?: Partial<AICard>,
+  ): OciPackageResult {
+    const aiCard = this.identityToAICard(identity, extra);
+    const aiCardJson = JSON.stringify(aiCard, null, 2);
+    const aiCardDescriptor = this.createDescriptor(aiCardJson, AI_CARD_MEDIA_TYPE, {
+      'org.opencontainers.image.title': 'ai-card.json',
+    });
+
+    const layers: Array<{ descriptor: OciDescriptor; content: string }> = [
+      { descriptor: aiCardDescriptor, content: aiCardJson },
+    ];
+
+    if (policyRules && policyRules.length > 0) {
+      const policyJson = JSON.stringify({ rules: policyRules }, null, 2);
+      const policyDescriptor = this.createDescriptor(policyJson, POLICY_MEDIA_TYPE, {
+        'org.opencontainers.image.title': 'policy.json',
+      });
+      layers.push({ descriptor: policyDescriptor, content: policyJson });
+    }
+
+    const configContent = JSON.stringify({
+      created: new Date().toISOString(),
+      author: identity.organization ?? identity.sponsor ?? 'unknown',
+      agent: { did: identity.did, name: identity.name },
+    });
+    const configDescriptor = this.createDescriptor(configContent, OCI_CONFIG_MEDIA_TYPE);
+
+    const manifest: OciManifest = {
+      schemaVersion: 2,
+      mediaType: OCI_MANIFEST_MEDIA_TYPE,
+      config: configDescriptor,
+      layers: layers.map((l) => l.descriptor),
+      annotations: {
+        'org.opencontainers.image.title': identity.name ?? identity.did,
+        'org.opencontainers.image.description': identity.description ?? '',
+        'org.opencontainers.image.vendor': identity.organization ?? '',
+        'dev.ai-card.version': aiCard.version,
+        'dev.agt.did': identity.did,
+      },
+    };
+
+    return { manifest, aiCard, configBlob: configContent, layers };
+  }
+
+  /**
+   * Extract an AI Card from an OCI manifest's layers.
+   */
+  unpackAICard(layers: Array<{ descriptor: OciDescriptor; content: string }>): AICard | null {
+    const aiCardLayer = layers.find((l) => l.descriptor.mediaType === AI_CARD_MEDIA_TYPE);
+    if (!aiCardLayer) return null;
+
+    try {
+      return JSON.parse(aiCardLayer.content) as AICard;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Extract policy rules from an OCI manifest's layers.
+   */
+  unpackPolicies(layers: Array<{ descriptor: OciDescriptor; content: string }>): PolicyRule[] {
+    const policyLayer = layers.find((l) => l.descriptor.mediaType === POLICY_MEDIA_TYPE);
+    if (!policyLayer) return [];
+
+    try {
+      const parsed = JSON.parse(policyLayer.content) as { rules: PolicyRule[] };
+      return parsed.rules ?? [];
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Verify the integrity of an OCI manifest by checking layer digests.
+   */
+  verifyManifest(
+    manifest: OciManifest,
+    layers: Array<{ descriptor: OciDescriptor; content: string }>,
+    configContent?: string,
+  ): { valid: boolean; errors: string[] } {
+    const errors: string[] = [];
+
+    if (manifest.schemaVersion !== 2) {
+      errors.push(`Unsupported schema version: ${manifest.schemaVersion}`);
+    }
+
+    // Verify config digest
+    if (configContent) {
+      const expectedDigest = this.sha256Digest(configContent);
+      if (manifest.config.digest !== expectedDigest) {
+        errors.push(`Config digest mismatch: expected ${expectedDigest}, got ${manifest.config.digest}`);
+      }
+    }
+
+    // Verify layer digests
+    for (const layer of layers) {
+      const expectedDigest = this.sha256Digest(layer.content);
+      if (layer.descriptor.digest !== expectedDigest) {
+        errors.push(
+          `Layer digest mismatch for ${layer.descriptor.annotations?.['org.opencontainers.image.title'] ?? 'unknown'}: expected ${expectedDigest}, got ${layer.descriptor.digest}`,
+        );
+      }
+
+      const expectedSize = Buffer.byteLength(layer.content, 'utf-8');
+      if (layer.descriptor.size !== expectedSize) {
+        errors.push(
+          `Layer size mismatch: expected ${expectedSize}, got ${layer.descriptor.size}`,
+        );
+      }
+    }
+
+    return { valid: errors.length === 0, errors };
+  }
+
+  // ── Internal helpers ──
+
+  private createDescriptor(
+    content: string,
+    mediaType: string,
+    annotations?: Record<string, string>,
+  ): OciDescriptor {
+    return {
+      mediaType,
+      digest: this.sha256Digest(content),
+      size: Buffer.byteLength(content, 'utf-8'),
+      annotations,
+    };
+  }
+
+  private sha256Digest(content: string): string {
+    const hash = createHash('sha256').update(content, 'utf-8').digest('hex');
+    return `sha256:${hash}`;
+  }
+
+  private capabilitiesToAICard(capabilities: string[]): AICardCapabilities {
+    return {
+      domains: capabilities,
+      input_modes: ['text'],
+      output_modes: ['text', 'json'],
+    };
+  }
+
+  private aiCardToCapabilities(capabilities?: AICardCapabilities): string[] {
+    if (!capabilities) return [];
+    return capabilities.domains ?? [];
+  }
+}

agent-governance-typescript/src/types.ts

@@ -394,6 +394,72 @@ export interface ContextIsolationViolation {
   description: string;
 }
 
+// ΓöÇΓöÇ OCI Manifest Adapter ΓöÇΓöÇ
+
+/** OCI manifest format (v2 schema). */
+export interface OciManifest {
+  schemaVersion: 2;
+  mediaType: string;
+  config: OciDescriptor;
+  layers: OciDescriptor[];
+  annotations?: Record<string, string>;
+}
+
+/** OCI content descriptor. */
+export interface OciDescriptor {
+  mediaType: string;
+  digest: string;
+  size: number;
+  annotations?: Record<string, string>;
+}
+
+/** AI Card agent metadata (framework-neutral). */
+export interface AICard {
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  license?: string;
+  homepage?: string;
+  repository?: string;
+  skills?: AICardSkill[];
+  capabilities?: AICardCapabilities;
+  invocation?: AICardInvocation;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AICardSkill {
+  name: string;
+  description?: string;
+  parameters?: Record<string, string>;
+  returns?: string;
+}
+
+export interface AICardCapabilities {
+  languages?: string[];
+  domains?: string[];
+  input_modes?: string[];
+  output_modes?: string[];
+  streaming?: boolean;
+  async?: boolean;
+}
+
+export interface AICardInvocation {
+  protocol?: string;
+  endpoint?: string;
+  authentication?: { type: string; required: boolean };
+  method?: string;
+  format?: string;
+}
+
+/** Result of converting AGT identity to OCI manifest. */
+export interface OciPackageResult {
+  manifest: OciManifest;
+  aiCard: AICard;
+  configBlob: string;
+  layers: Array<{ descriptor: OciDescriptor; content: string }>;
+}
+
 // ΓöÇΓöÇ Audit ΓöÇΓöÇ
 
 export interface AuditConfig {