@enactprotocol/api 2.0.0

package/src/download.ts

@@ -0,0 +1,298 @@
+/**
+ * Tool download functionality
+ * Implements bundle download and tool info retrieval
+ */
+
+import type { EnactApiClient } from "./client";
+import type { ToolMetadata, ToolVersionDetails } from "./types";
+
+/**
+ * Download options
+ */
+export interface DownloadOptions {
+  /** Tool name (e.g., "alice/utils/greeter") */
+  name: string;
+  /** Tool version (e.g., "1.2.0") */
+  version: string;
+  /** Verify bundle hash after download */
+  verify?: boolean | undefined;
+}
+
+/**
+ * Download result
+ */
+export interface DownloadResult {
+  /** Downloaded bundle data */
+  data: ArrayBuffer;
+  /** Bundle hash (sha256) */
+  hash: string;
+  /** Content length in bytes */
+  size: number;
+  /** Content type */
+  contentType: string;
+}
+
+/**
+ * Tool info (metadata) v2
+ */
+export interface ToolInfo {
+  /** Tool name */
+  name: string;
+  /** Tool description */
+  description: string;
+  /** Tool tags */
+  tags: string[];
+  /** SPDX license */
+  license: string;
+  /** Author info */
+  author: {
+    username: string;
+    avatarUrl?: string | undefined;
+  };
+  /** Repository URL */
+  repository?: string | undefined;
+  /** Creation timestamp */
+  createdAt: Date;
+  /** Last update timestamp */
+  updatedAt: Date;
+  /** Latest version */
+  latestVersion: string;
+  /** All available versions (paginated) */
+  versions: Array<{
+    version: string;
+    publishedAt: Date;
+    downloads: number;
+    bundleHash: string;
+    yanked: boolean;
+  }>;
+  /** Total number of versions */
+  versionsTotal: number;
+  /** Total downloads */
+  totalDownloads: number;
+}
+
+/**
+ * Version-specific tool info v2
+ */
+export interface ToolVersionInfo {
+  /** Tool name */
+  name: string;
+  /** Version */
+  version: string;
+  /** Description */
+  description: string;
+  /** License */
+  license: string;
+  /** Whether yanked */
+  yanked: boolean;
+  /** Yank reason */
+  yankReason?: string | undefined;
+  /** Replacement version */
+  yankReplacement?: string | undefined;
+  /** Yanked timestamp */
+  yankedAt?: Date | undefined;
+  /** Full manifest */
+  manifest: Record<string, unknown>;
+  /** Bundle info */
+  bundle: {
+    hash: string;
+    size: number;
+    downloadUrl: string;
+  };
+  /** Attestations */
+  attestations: Array<{
+    auditor: string;
+    auditorProvider: string;
+    signedAt: Date;
+    rekorLogId: string;
+    verified: boolean;
+  }>;
+  /** Published by */
+  publishedBy: {
+    username: string;
+    avatarUrl?: string | undefined;
+  };
+  /** Publication timestamp */
+  publishedAt: Date;
+  /** Download count */
+  downloads: number;
+}
+
+/**
+ * Convert raw tool metadata to ToolInfo
+ */
+function toToolInfo(raw: ToolMetadata): ToolInfo {
+  return {
+    name: raw.name,
+    description: raw.description,
+    tags: raw.tags,
+    license: raw.license,
+    author: {
+      username: raw.author.username,
+      avatarUrl: raw.author.avatar_url,
+    },
+    repository: raw.repository,
+    createdAt: new Date(raw.created_at),
+    updatedAt: new Date(raw.updated_at),
+    latestVersion: raw.latest_version,
+    versions: raw.versions.map((v) => ({
+      version: v.version,
+      publishedAt: new Date(v.published_at),
+      downloads: v.downloads,
+      bundleHash: v.bundle_hash,
+      yanked: v.yanked,
+    })),
+    versionsTotal: raw.versions_total,
+    totalDownloads: raw.total_downloads,
+  };
+}
+
+/**
+ * Convert raw version details to ToolVersionInfo
+ */
+function toToolVersionInfo(raw: ToolVersionDetails): ToolVersionInfo {
+  return {
+    name: raw.name,
+    version: raw.version,
+    description: raw.description,
+    license: raw.license,
+    yanked: raw.yanked,
+    yankReason: raw.yank_reason,
+    yankReplacement: raw.yank_replacement,
+    yankedAt: raw.yanked_at ? new Date(raw.yanked_at) : undefined,
+    manifest: raw.manifest,
+    bundle: {
+      hash: raw.bundle.hash,
+      size: raw.bundle.size,
+      downloadUrl: raw.bundle.download_url,
+    },
+    attestations: raw.attestations.map((a) => ({
+      auditor: a.auditor,
+      auditorProvider: a.auditor_provider,
+      signedAt: new Date(a.signed_at),
+      rekorLogId: a.rekor_log_id,
+      verified: a.verification?.verified ?? false,
+    })),
+    publishedBy: {
+      username: raw.published_by.username,
+      avatarUrl: raw.published_by.avatar_url,
+    },
+    publishedAt: new Date(raw.published_at),
+    downloads: raw.downloads,
+  };
+}
+
+/**
+ * Get tool metadata
+ *
+ * @param client - API client instance
+ * @param name - Tool name (e.g., "alice/utils/greeter")
+ * @returns Tool metadata
+ *
+ * @example
+ * ```ts
+ * const info = await getToolInfo(client, "alice/utils/greeter");
+ * console.log(info.latestVersion);
+ * ```
+ */
+export async function getToolInfo(client: EnactApiClient, name: string): Promise<ToolInfo> {
+  const response = await client.get<ToolMetadata>(`/tools/${name}`);
+  return toToolInfo(response.data);
+}
+
+/**
+ * Get version-specific tool information
+ *
+ * @param client - API client instance
+ * @param name - Tool name
+ * @param version - Tool version
+ * @returns Version-specific tool info
+ */
+export async function getToolVersion(
+  client: EnactApiClient,
+  name: string,
+  version: string
+): Promise<ToolVersionInfo> {
+  const response = await client.get<ToolVersionDetails>(`/tools/${name}/versions/${version}`);
+  return toToolVersionInfo(response.data);
+}
+
+/**
+ * Get attestations for a tool version
+ *
+ * @param client - API client instance
+ * @param name - Tool name
+ * @param version - Tool version
+ * @returns Attestation list
+ */
+export async function getAttestations(
+  client: EnactApiClient,
+  name: string,
+  version: string
+): Promise<
+  Array<{
+    auditor: string;
+    auditorProvider: string;
+    signedAt: Date;
+    rekorLogId: string;
+    verified: boolean;
+  }>
+> {
+  const response = await client.get<ToolVersionDetails>(`/tools/${name}/versions/${version}`);
+  return response.data.attestations.map((a) => ({
+    auditor: a.auditor,
+    auditorProvider: a.auditor_provider,
+    signedAt: new Date(a.signed_at),
+    rekorLogId: a.rekor_log_id,
+    verified: a.verification?.verified ?? false,
+  }));
+}
+
+/**
+ * Download a tool bundle (v2 with yank handling)
+ *
+ * @param client - API client instance
+ * @param options - Download options
+ * @returns Downloaded bundle data with metadata
+ *
+ * @example
+ * ```ts
+ * const result = await downloadBundle(client, {
+ *   name: "alice/utils/greeter",
+ *   version: "1.2.0",
+ *   verify: true
+ * });
+ * await Bun.write("bundle.tar.gz", result.data);
+ * ```
+ */
+export async function downloadBundle(
+  client: EnactApiClient,
+  options: DownloadOptions & { acknowledgeYanked?: boolean }
+): Promise<DownloadResult> {
+  const { name, version, acknowledgeYanked } = options;
+
+  // Build query params for yanked version acknowledgment
+  const params = acknowledgeYanked ? "?acknowledge_yanked=true" : "";
+  const response = await client.download(`/tools/${name}/versions/${version}/download${params}`);
+
+  const data = await response.arrayBuffer();
+  const contentType = response.headers.get("Content-Type") ?? "application/gzip";
+  const size = data.byteLength;
+
+  // Extract hash from ETag or compute it
+  let hash = response.headers.get("ETag")?.replace(/"/g, "") ?? "";
+
+  // If verify is true and we need to compute hash, do it
+  if (options.verify && !hash.startsWith("sha256:")) {
+    const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    hash = `sha256:${hashArray.map((b) => b.toString(16).padStart(2, "0")).join("")}`;
+  }
+
+  return {
+    data,
+    hash,
+    size,
+    contentType,
+  };
+}

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * @enactprotocol/api - Registry API client for Enact tools (v2)
+ *
+ * This package provides HTTP client functionality for interacting with
+ * the Enact registry v2, including:
+ * - OAuth authentication
+ * - Tool search and discovery
+ * - Bundle download with yank handling
+ * - Tool publishing (multipart upload)
+ * - Attestation management
+ * - Trust configuration
+ *
+ * @packageDocumentation
+ */
+
+export const VERSION = "0.2.0";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export * from "./types";
+
+// =============================================================================
+// Client
+// =============================================================================
+
+export { EnactApiClient, createApiClient } from "./client";
+export type { ApiClientOptions } from "./client";
+
+// =============================================================================
+// Search
+// =============================================================================
+
+export { searchTools } from "./search";
+export type { SearchOptions, SearchResult, SearchResponse } from "./search";
+
+// =============================================================================
+// Download
+// =============================================================================
+
+export { downloadBundle, getToolInfo, getToolVersion, getAttestations } from "./download";
+export type { DownloadOptions, DownloadResult, ToolInfo, ToolVersionInfo } from "./download";
+
+// =============================================================================
+// Publish
+// =============================================================================
+
+export {
+  publishTool,
+  createBundle,
+  submitAttestation,
+  yankVersion,
+  unyankVersion,
+  deleteTool,
+} from "./publish";
+export type {
+  PublishOptions,
+  PublishResult,
+  BundleInfo,
+  SubmitAttestationOptions,
+  AttestationResult,
+} from "./publish";
+
+// =============================================================================
+// Auth (v2 OAuth)
+// =============================================================================
+
+export {
+  initiateLogin,
+  exchangeCodeForToken,
+  refreshAccessToken,
+  getCurrentUser,
+  authenticate,
+  logout,
+  getAuthStatus,
+  getUserProfile,
+  submitFeedback,
+} from "./auth";
+export type { AuthResult, AuthStatus } from "./auth";
+
+// =============================================================================
+// Attestations (v2)
+// =============================================================================
+
+export {
+  getAttestations as getAttestationList,
+  submitAttestation as submitAttestationToRegistry,
+  revokeAttestation,
+  hasAttestation,
+  getAttestationBundle,
+  verifyAttestationLocally,
+  verifyAllAttestations,
+  hasTrustedAttestation,
+} from "./attestations";
+export type { AttestationListResponse, VerifiedAuditor } from "./attestations";
+
+// =============================================================================
+// Trust (v2)
+// =============================================================================
+
+export {
+  getUserTrust,
+  updateMyTrust,
+  addTrustedAuditor,
+  removeTrustedAuditor,
+  userTrustsAuditor,
+  getMyTrustedAuditors,
+} from "./trust";

package/src/publish.ts

@@ -0,0 +1,316 @@
+/**
+ * Tool publishing functionality (v2)
+ * Implements bundle creation and publishing to registry
+ */
+
+import type { EnactApiClient } from "./client";
+import type { AttestationResponse, PublishResponse } from "./types";
+
+/**
+ * Publish options
+ */
+export interface PublishOptions {
+  /** Tool name (e.g., "alice/utils/greeter") */
+  name: string;
+  /** Tool version (e.g., "1.2.0") */
+  version: string;
+  /** Bundle data (tar.gz) */
+  bundle: ArrayBuffer | Uint8Array;
+}
+
+/**
+ * Publish result
+ */
+export interface PublishResult {
+  /** Tool name */
+  name: string;
+  /** Published version */
+  version: string;
+  /** Publication timestamp */
+  publishedAt: Date;
+  /** Bundle hash */
+  bundleHash: string;
+}
+
+/**
+ * Bundle info (for createBundle)
+ */
+export interface BundleInfo {
+  /** Bundle data */
+  data: Uint8Array;
+  /** SHA-256 hash */
+  hash: string;
+  /** Size in bytes */
+  size: number;
+}
+
+/**
+ * Attestation submission options (v2)
+ */
+export interface SubmitAttestationOptions {
+  /** Tool name */
+  name: string;
+  /** Tool version */
+  version: string;
+  /** Sigstore bundle (full bundle object) */
+  sigstoreBundle: Record<string, unknown>;
+}
+
+/**
+ * Attestation submission result (v2)
+ */
+export interface AttestationResult {
+  /** Auditor email */
+  auditor: string;
+  /** OAuth provider */
+  auditorProvider: string;
+  /** Signing timestamp */
+  signedAt: Date;
+  /** Rekor log ID */
+  rekorLogId: string;
+  /** Rekor log index */
+  rekorLogIndex?: number | undefined;
+  /** Verification result */
+  verification: {
+    verified: boolean;
+    verifiedAt: Date;
+    rekorVerified: boolean;
+    certificateVerified: boolean;
+    signatureVerified: boolean;
+  };
+}
+
+/**
+ * Create a bundle from tool directory
+ *
+ * This is a placeholder that would typically:
+ * 1. Read all files from the tool directory
+ * 2. Create a tar.gz archive
+ * 3. Compute SHA-256 hash
+ *
+ * @param toolDir - Path to tool directory
+ * @returns Bundle info with data and hash
+ */
+export async function createBundle(toolDir: string): Promise<BundleInfo> {
+  // This would use @enactprotocol/shared utilities to:
+  // 1. Read files from toolDir
+  // 2. Create tarball
+  // 3. Compute hash
+
+  // For now, this is a placeholder that throws
+  // The actual implementation would integrate with the shared package
+  throw new Error(`createBundle not yet implemented for: ${toolDir}`);
+}
+
+/**
+ * Publish a tool to the registry (v2 - multipart upload)
+ *
+ * @param client - API client instance (must be authenticated)
+ * @param options - Publish options with manifest and bundle
+ * @returns Publish result
+ *
+ * @example
+ * ```ts
+ * const bundle = await createBundle("./my-tool");
+ * const result = await publishTool(client, {
+ *   name: "alice/utils/greeter",
+ *   manifest: { enact: "2.0.0", name: "alice/utils/greeter", version: "1.2.0", ... },
+ *   bundle: bundle.data,
+ *   readme: "# My Tool\n\nDescription..."
+ * });
+ * console.log(`Published: ${result.bundleHash}`);
+ * ```
+ */
+export async function publishTool(
+  client: EnactApiClient,
+  options: {
+    name: string;
+    manifest: Record<string, unknown>;
+    bundle: ArrayBuffer | Uint8Array;
+    readme?: string | undefined;
+  }
+): Promise<PublishResult> {
+  const { name, manifest, bundle, readme } = options;
+
+  // Create FormData for multipart upload
+  const formData = new FormData();
+
+  // Add manifest as JSON
+  formData.append("manifest", JSON.stringify(manifest));
+
+  // Add bundle as file
+  const bundleBlob =
+    bundle instanceof ArrayBuffer
+      ? new Blob([bundle], { type: "application/gzip" })
+      : new Blob([bundle], { type: "application/gzip" });
+  formData.append("bundle", bundleBlob, "bundle.tar.gz");
+
+  // Add optional readme
+  if (readme) {
+    formData.append("readme", readme);
+  }
+
+  // Make multipart request (v2 endpoint is POST /tools/{name})
+  const response = await fetch(`${client.getBaseUrl()}/tools/${name}`, {
+    method: "POST",
+    headers: {
+      Authorization: client.getAuthToken() ? `Bearer ${client.getAuthToken()}` : "",
+      "User-Agent": client.getUserAgent() || "enact-cli/0.1.0",
+    },
+    body: formData,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Publish failed: ${response.status} - ${errorText}`);
+  }
+
+  const json = (await response.json()) as { data: PublishResponse } | PublishResponse;
+  // Handle both wrapped and unwrapped responses
+  const data = "data" in json ? json.data : json;
+
+  return {
+    name: data.name,
+    version: data.version,
+    publishedAt: new Date(data.published_at),
+    bundleHash: data.bundle_hash,
+  };
+}
+
+/**
+ * Submit an attestation for a tool version (v2)
+ *
+ * @param client - API client instance (must be authenticated via OIDC)
+ * @param options - Attestation options
+ * @returns Attestation result
+ */
+export async function submitAttestation(
+  client: EnactApiClient,
+  options: SubmitAttestationOptions
+): Promise<AttestationResult> {
+  const { name, version, sigstoreBundle } = options;
+
+  const response = await client.post<AttestationResponse>(
+    `/tools/${name}/versions/${version}/attestations`,
+    {
+      bundle: sigstoreBundle,
+    }
+  );
+
+  return {
+    auditor: response.data.auditor,
+    auditorProvider: response.data.auditor_provider,
+    signedAt: new Date(response.data.signed_at),
+    rekorLogId: response.data.rekor_log_id,
+    rekorLogIndex: response.data.rekor_log_index,
+    verification: {
+      verified: response.data.verification.verified,
+      verifiedAt: new Date(response.data.verification.verified_at),
+      rekorVerified: response.data.verification.rekor_verified,
+      certificateVerified: response.data.verification.certificate_verified,
+      signatureVerified: response.data.verification.signature_verified,
+    },
+  };
+}
+
+/**
+ * Yank a tool version (v2)
+ *
+ * Yanked versions remain downloadable but are excluded from version listings
+ * by default and show warnings to users.
+ *
+ * @param client - API client instance (must be authenticated and owner)
+ * @param name - Tool name
+ * @param version - Version to yank
+ * @param options - Yank options (reason, replacement)
+ * @returns Yank result
+ *
+ * @example
+ * ```ts
+ * const result = await yankVersion(client, "alice/utils/greeter", "1.1.0", {
+ *   reason: "Security vulnerability CVE-2025-1234",
+ *   replacementVersion: "1.2.0"
+ * });
+ * ```
+ */
+export async function yankVersion(
+  client: EnactApiClient,
+  name: string,
+  version: string,
+  options?: {
+    reason?: string | undefined;
+    replacementVersion?: string | undefined;
+  }
+): Promise<{
+  yanked: true;
+  version: string;
+  reason?: string | undefined;
+  replacementVersion?: string | undefined;
+  yankedAt: Date;
+}> {
+  const response = await client.post<{
+    yanked: true;
+    version: string;
+    reason?: string | undefined;
+    replacement_version?: string | undefined;
+    yanked_at: string;
+  }>(`/tools/${name}/versions/${version}/yank`, {
+    reason: options?.reason,
+    replacement_version: options?.replacementVersion,
+  });
+
+  return {
+    yanked: response.data.yanked,
+    version: response.data.version,
+    reason: response.data.reason,
+    replacementVersion: response.data.replacement_version,
+    yankedAt: new Date(response.data.yanked_at),
+  };
+}
+
+/**
+ * Unyank a tool version (v2)
+ *
+ * Restore a previously yanked version.
+ *
+ * @param client - API client instance (must be authenticated and owner)
+ * @param name - Tool name
+ * @param version - Version to unyank
+ * @returns Unyank result
+ *
+ * @example
+ * ```ts
+ * const result = await unyankVersion(client, "alice/utils/greeter", "1.1.0");
+ * ```
+ */
+export async function unyankVersion(
+  client: EnactApiClient,
+  name: string,
+  version: string
+): Promise<{
+  yanked: false;
+  version: string;
+  unyankedAt: Date;
+}> {
+  const response = await client.post<{
+    yanked: false;
+    version: string;
+    unyanked_at: string;
+  }>(`/tools/${name}/versions/${version}/unyank`);
+
+  return {
+    yanked: response.data.yanked,
+    version: response.data.version,
+    unyankedAt: new Date(response.data.unyanked_at),
+  };
+}
+
+/**
+ * Delete a tool from the registry
+ *
+ * @param client - API client instance (must be authenticated and owner)
+ * @param name - Tool name to delete
+ */
+export async function deleteTool(client: EnactApiClient, name: string): Promise<void> {
+  await client.delete(`/tools/${name}`);
+}