AMPR-154 #463: add plugin bundle format spec (#473)

Adds the W0.6 portable plugin bundle format: layout doc,
PluginBundle data class with bundleFormatVersion, parser
returning typed errors (missing/invalid manifest, oversized,
unknown version), schema+permission validator, and a stubbed
signature verifier surface so the W1.10 marketplace UI can
import against a stable contract while production crypto is
still pending. Ships in-memory, directory, and ZIP sources
(commonMain + jvmMain).

Closes #463

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wow-miley

ampere-core/src/commonMain/kotlin/link/socket/ampere/bundle/OkioPluginBundleSource.kt

@@ -0,0 +1,63 @@
+package link.socket.ampere.bundle
+
+import okio.FileSystem
+import okio.IOException
+import okio.Path
+
+/**
+ * [PluginBundleSource] backed by an okio [FileSystem].
+ *
+ * Used by [PluginBundleSource.fromDirectory] (commonMain) and
+ * `PluginBundleSource.fromZipFile` (jvmMain — okio's `openZip` is JVM-only
+ * in this version).
+ *
+ * Entry keys are normalised to forward-slash paths relative to the bundle
+ * root, so a bundle imported as a directory and the same bundle imported as a
+ * ZIP produce identical [PluginBundleSource.entries] sets.
+ */
+internal class OkioPluginBundleSource(
+    private val fileSystem: FileSystem,
+    private val root: Path,
+) : PluginBundleSource {
+
+    private val index: Map<String, Path> by lazy { buildIndex() }
+
+    override fun entries(): Set<String> = index.keys
+
+    override fun readEntry(path: String): ByteArray? {
+        val resolved = index[path] ?: return null
+        return try {
+            fileSystem.read(resolved) { readByteArray() }
+        } catch (e: IOException) {
+            null
+        }
+    }
+
+    override fun totalSize(): Long =
+        index.values.sumOf { fileSystem.metadataOrNull(it)?.size ?: 0L }
+
+    private fun buildIndex(): Map<String, Path> {
+        val rootMeta = fileSystem.metadataOrNull(root) ?: return emptyMap()
+        if (!rootMeta.isDirectory) return emptyMap()
+
+        val entries = mutableMapOf<String, Path>()
+        for (entry in fileSystem.listRecursively(root)) {
+            val meta = fileSystem.metadataOrNull(entry) ?: continue
+            if (!meta.isRegularFile) continue
+            val key = entry.relativeTo(root).toString().replace('\\', '/')
+            if (key.isNotEmpty()) entries[key] = entry
+        }
+        return entries
+    }
+}
+
+/**
+ * Reads a bundle from an unpacked directory at [directory].
+ *
+ * If [directory] does not exist or is not a directory, the returned source
+ * is empty and the parser will surface [BundleParseError.MissingManifest].
+ */
+fun PluginBundleSource.Companion.fromDirectory(
+    directory: Path,
+    fileSystem: FileSystem,
+): PluginBundleSource = OkioPluginBundleSource(fileSystem, directory)

ampere-core/src/commonMain/kotlin/link/socket/ampere/bundle/PluginBundle.kt

@@ -0,0 +1,95 @@
+package link.socket.ampere.bundle
+
+import kotlinx.serialization.Serializable
+import link.socket.ampere.plugin.PluginManifest
+
+/**
+ * Bundle format version supported by this build.
+ *
+ * Bumping this constant signals a structural change to the bundle layout (file
+ * names, required entries, on-disk encoding). Field-level additions to
+ * [PluginManifest] do not require a bump.
+ */
+const val CURRENT_BUNDLE_FORMAT_VERSION: Int = 1
+
+/**
+ * Path of the manifest file at the root of every bundle.
+ */
+const val BUNDLE_MANIFEST_PATH: String = "manifest.json"
+
+/**
+ * Optional asset directory prefix. Files under this path are surfaced as
+ * [PluginBundle.assets] keyed by their path relative to the bundle root.
+ */
+const val BUNDLE_ASSETS_PREFIX: String = "assets/"
+
+/**
+ * Optional detached signature for the manifest. Production verification arrives
+ * in a follow-up; today the file is read into [PluginBundle.signature] verbatim
+ * so the parser surface matches what marketplace UI imports against.
+ */
+const val BUNDLE_SIGNATURE_PATH: String = "signature.sig"
+
+/**
+ * On-disk representation of `manifest.json`.
+ *
+ * Wrapping [PluginManifest] keeps the W0.1 plugin contract untouched while
+ * letting the bundle format declare its own [bundleFormatVersion]. Older
+ * manifests written before the bundle spec lacked this wrapper; the parser
+ * does not attempt to read those — bundle import is opt-in for plugins
+ * shipping through the marketplace.
+ */
+@Serializable
+data class BundleManifest(
+    val bundleFormatVersion: Int,
+    val plugin: PluginManifest,
+)
+
+/**
+ * A successfully parsed plugin bundle.
+ *
+ * @property bundleFormatVersion the format version declared by the bundle, as
+ *   read from `manifest.json`. Validated against [CURRENT_BUNDLE_FORMAT_VERSION]
+ *   by the parser before this value is observable.
+ * @property manifest the W0.1 [PluginManifest] embedded in the bundle.
+ * @property assets file contents from `assets/`, keyed by path relative to the
+ *   bundle root (e.g. `assets/icon.png`). Empty when the bundle has no assets.
+ * @property signature raw bytes of `signature.sig` if present. Verification is
+ *   the responsibility of [PluginBundleSignatureVerifier]; the parser does not
+ *   inspect the bytes.
+ */
+data class PluginBundle(
+    val bundleFormatVersion: Int,
+    val manifest: PluginManifest,
+    val assets: Map<String, ByteArray>,
+    val signature: ByteArray?,
+) {
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (other !is PluginBundle) return false
+        if (bundleFormatVersion != other.bundleFormatVersion) return false
+        if (manifest != other.manifest) return false
+        if (assets.keys != other.assets.keys) return false
+        for ((path, bytes) in assets) {
+            if (!bytes.contentEquals(other.assets[path])) return false
+        }
+        if (signature == null) {
+            if (other.signature != null) return false
+        } else {
+            if (other.signature == null) return false
+            if (!signature.contentEquals(other.signature)) return false
+        }
+        return true
+    }
+
+    override fun hashCode(): Int {
+        var result = bundleFormatVersion
+        result = 31 * result + manifest.hashCode()
+        for ((path, bytes) in assets) {
+            result = 31 * result + path.hashCode()
+            result = 31 * result + bytes.contentHashCode()
+        }
+        result = 31 * result + (signature?.contentHashCode() ?: 0)
+        return result
+    }
+}

ampere-core/src/commonMain/kotlin/link/socket/ampere/bundle/PluginBundleParser.kt

@@ -0,0 +1,127 @@
+package link.socket.ampere.bundle
+
+import kotlinx.serialization.SerializationException
+import kotlinx.serialization.json.Json
+
+/**
+ * Maximum total byte size accepted by [PluginBundleParser].
+ *
+ * Bundles are user-importable artefacts; the cap prevents a malicious or
+ * malformed archive from exhausting memory before validation begins. The
+ * value is intentionally generous — current first-party plugins ship under
+ * 1 MiB, but bundled assets (icons, sample data) can grow.
+ */
+const val MAX_BUNDLE_SIZE_BYTES: Long = 50L * 1024 * 1024
+
+/**
+ * Outcome of [PluginBundleParser.parse]. Either a parsed bundle or a typed
+ * error describing why parsing failed.
+ */
+sealed interface BundleParseResult {
+
+    data class Ok(val bundle: PluginBundle) : BundleParseResult
+
+    data class Failed(val error: BundleParseError) : BundleParseResult
+}
+
+/**
+ * Reasons a bundle may fail to parse. The list is closed; callers can rely on
+ * `when` being exhaustive.
+ */
+sealed interface BundleParseError {
+
+    /** The bundle has no `manifest.json` entry. */
+    data object MissingManifest : BundleParseError
+
+    /** `manifest.json` exists but is not valid JSON or does not match the schema. */
+    data class InvalidManifest(val message: String) : BundleParseError
+
+    /**
+     * Total entry size exceeds [MAX_BUNDLE_SIZE_BYTES].
+     *
+     * Reported with the actual size so callers (e.g. marketplace UI) can show
+     * the user how far over the limit a bundle ran.
+     */
+    data class BundleTooLarge(val sizeBytes: Long, val limitBytes: Long) : BundleParseError
+
+    /**
+     * The manifest declares a [bundleFormatVersion] this build does not
+     * understand. Distinguished from [InvalidManifest] so newer bundles
+     * surface a clear "upgrade required" message rather than looking
+     * malformed.
+     */
+    data class UnknownVersion(val declared: Int, val supported: Int) : BundleParseError
+}
+
+/**
+ * Parses a [PluginBundleSource] into a [PluginBundle].
+ *
+ * The parser only enforces structural rules that determine whether the
+ * bundle is *readable*: size cap, manifest presence, manifest schema, and
+ * format version. Semantic checks (permission well-formedness, id rules,
+ * etc.) are the responsibility of [PluginBundleValidator].
+ */
+class PluginBundleParser(
+    private val maxBundleSizeBytes: Long = MAX_BUNDLE_SIZE_BYTES,
+    private val supportedFormatVersion: Int = CURRENT_BUNDLE_FORMAT_VERSION,
+) {
+
+    private val json = Json {
+        ignoreUnknownKeys = true
+        classDiscriminator = "type"
+        encodeDefaults = true
+    }
+
+    fun parse(source: PluginBundleSource): BundleParseResult {
+        val totalSize = source.totalSize()
+        if (totalSize > maxBundleSizeBytes) {
+            return BundleParseResult.Failed(
+                BundleParseError.BundleTooLarge(
+                    sizeBytes = totalSize,
+                    limitBytes = maxBundleSizeBytes,
+                ),
+            )
+        }
+
+        val manifestBytes = source.readEntry(BUNDLE_MANIFEST_PATH)
+            ?: return BundleParseResult.Failed(BundleParseError.MissingManifest)
+
+        val bundleManifest = try {
+            json.decodeFromString(BundleManifest.serializer(), manifestBytes.decodeToString())
+        } catch (e: SerializationException) {
+            return BundleParseResult.Failed(
+                BundleParseError.InvalidManifest(e.message ?: "manifest.json failed to decode"),
+            )
+        } catch (e: IllegalArgumentException) {
+            return BundleParseResult.Failed(
+                BundleParseError.InvalidManifest(e.message ?: "manifest.json failed to decode"),
+            )
+        }
+
+        if (bundleManifest.bundleFormatVersion != supportedFormatVersion) {
+            return BundleParseResult.Failed(
+                BundleParseError.UnknownVersion(
+                    declared = bundleManifest.bundleFormatVersion,
+                    supported = supportedFormatVersion,
+                ),
+            )
+        }
+
+        val assets = source.entries()
+            .asSequence()
+            .filter { it.startsWith(BUNDLE_ASSETS_PREFIX) && it != BUNDLE_ASSETS_PREFIX }
+            .mapNotNull { path -> source.readEntry(path)?.let { path to it } }
+            .toMap()
+
+        val signature = source.readEntry(BUNDLE_SIGNATURE_PATH)
+
+        return BundleParseResult.Ok(
+            PluginBundle(
+                bundleFormatVersion = bundleManifest.bundleFormatVersion,
+                manifest = bundleManifest.plugin,
+                assets = assets,
+                signature = signature,
+            ),
+        )
+    }
+}

ampere-core/src/commonMain/kotlin/link/socket/ampere/bundle/PluginBundleSignatureVerifier.kt

@@ -0,0 +1,62 @@
+package link.socket.ampere.bundle
+
+import co.touchlab.kermit.Logger
+
+/**
+ * Outcome of [PluginBundleSignatureVerifier.verify].
+ *
+ * [Verified.Skipped] and [Verified.Trusted] are both safe to surface as
+ * "verified" to the user, but marketplace UI (W1.10) is expected to badge
+ * them differently — `Skipped` exists only because production crypto has
+ * not landed yet, and lets unsigned bundles flow through the import pipeline
+ * during W0/W1 without forcing the importer to special-case `null`.
+ */
+sealed interface PluginBundleSignatureVerification {
+
+    sealed interface Verified : PluginBundleSignatureVerification {
+
+        /** A real signature was checked against a trusted key. */
+        data object Trusted : Verified
+
+        /** No verification was performed. Production crypto is deferred. */
+        data object Skipped : Verified
+    }
+
+    /** A signature was present but did not validate. Bundle must be rejected. */
+    data class Invalid(val reason: String) : PluginBundleSignatureVerification
+}
+
+/**
+ * Verifies the detached signature on a [PluginBundle].
+ *
+ * The interface exists today so marketplace UI can wire its import pipeline
+ * against a stable surface. The default implementation,
+ * [NoOpPluginBundleSignatureVerifier], always returns [Verified.Skipped]
+ * with a logged warning. A real, key-pinned implementation lands in a
+ * follow-up ticket.
+ */
+fun interface PluginBundleSignatureVerifier {
+
+    suspend fun verify(bundle: PluginBundle): PluginBundleSignatureVerification
+}
+
+/**
+ * Default no-op signature verifier.
+ *
+ * Logs a warning the first time it is invoked per process so a stray
+ * production deployment cannot silently bypass signature checks. The
+ * follow-up production verifier replaces this object entirely; do not extend
+ * it.
+ */
+object NoOpPluginBundleSignatureVerifier : PluginBundleSignatureVerifier {
+
+    private val log = Logger.withTag("ampere/bundle/signature")
+
+    override suspend fun verify(bundle: PluginBundle): PluginBundleSignatureVerification {
+        log.w {
+            "Signature verification is stubbed (no-op). " +
+                "Bundle '${bundle.manifest.id}' v${bundle.manifest.version} accepted without crypto."
+        }
+        return PluginBundleSignatureVerification.Verified.Skipped
+    }
+}