diff --git a/docs/plugin-platform/contract-and-sdk.md b/docs/plugin-platform/contract-and-sdk.md index 24ae595b6..383e7b10d 100644 --- a/docs/plugin-platform/contract-and-sdk.md +++ b/docs/plugin-platform/contract-and-sdk.md @@ -104,8 +104,10 @@ while macOS, Linux, and Windows native binaries remain distinct. A companion cannot declare the same target platform twice, and no two companion variants may claim the same package path. A manifest with companions must also provide a Node utility entrypoint and declare both `runtime.advanced` and a resource-bound -`companion.execute` permission. An ordinary browser placement cannot authorize -or launch a companion. +`companion.execute` permission. The first-party placement resolver selects the +utility entrypoint for companion manifests even when a browser entrypoint is +also present. An ordinary browser placement cannot authorize or launch a +companion. ## Contribution identity diff --git a/docs/plugin-platform/security-and-permissions.md b/docs/plugin-platform/security-and-permissions.md index 510089389..53bcd7405 100644 --- a/docs/plugin-platform/security-and-permissions.md +++ b/docs/plugin-platform/security-and-permissions.md @@ -80,7 +80,8 @@ authority. Phase 9 must also require a verified publisher principal before the advanced path can be publicly enabled. Required resource-scoped permissions (`network`, filesystem read/write, and -companion execution) must declare non-empty activation-time resource bounds. +companion execution) must declare non-empty activation-time resource bounds; +the all-resources `*` wildcard is not a valid bound. The string shorthand remains available only for optional declarations, whose concrete resource is approved on first use. A package update therefore cannot activate first and defer a newly required resource decision until later. @@ -88,6 +89,8 @@ activate first and defer a newly required resource decision until later. Native companions are an advanced-runtime capability. Their manifests require a Node utility entrypoint plus `runtime.advanced`, and `companion.start` rejects browser runtime identities before permission middleware can persist a grant. +The first-party placement path selects the utility runtime whenever companions +are declared, including manifests that also provide a browser entrypoint. The supervisor repeats the placement check immediately before reserving or spawning a process. Phase 9 adds verified publisher trust to this same boundary. diff --git a/electron/plugins/generated/plugin-contract.schema.json b/electron/plugins/generated/plugin-contract.schema.json index 8bbb2f574..93c39d10e 100644 --- a/electron/plugins/generated/plugin-contract.schema.json +++ b/electron/plugins/generated/plugin-contract.schema.json @@ -300,12 +300,31 @@ "provider.importer" ] }, + "ResourceScopedPermission": { + "description": "A permission whose approval must be constrained to explicit canonical resources.", + "type": "string", + "enum": [ + "network", + "filesystem.read", + "filesystem.write", + "companion.execute" + ] + }, "PermissionResource": { "description": "A host-canonicalized permission resource. Filesystem resources may be absolute platform paths; other permission kinds impose narrower runtime limits.", "type": "string", "minLength": 1, "maxLength": 8192 }, + "BoundedPermissionResource": { + "description": "An explicit resource bound; the all-resources wildcard is not an activation-time bound.", + "type": "string", + "minLength": 1, + "maxLength": 8192, + "not": { + "const": "*" + } + }, "PermissionResourceKind": { "description": "Whether a canonical resource grant covers only that resource or a filesystem directory subtree.", "type": "string", @@ -350,6 +369,32 @@ } ] }, + "RequiredPermissionResourceDeclaration": { + "type": "object", + "required": [ + "permission", + "resources" + ], + "properties": { + "permission": { + "$ref": "#/$defs/ResourceScopedPermission" + }, + "resources": { + "type": "array", + "minItems": 1, + "maxItems": 128, + "uniqueItems": true, + "items": { + "$ref": "#/$defs/BoundedPermissionResource" + } + }, + "reason": { + "type": "string", + "maxLength": 1024 + } + }, + "additionalProperties": false + }, "RequiredPermissionDeclaration": { "description": "Required resource-scoped permissions must name their complete activation-time approval bounds.", "oneOf": [ @@ -357,7 +402,7 @@ "$ref": "#/$defs/NonResourceScopedPermission" }, { - "$ref": "#/$defs/PermissionResourceDeclaration" + "$ref": "#/$defs/RequiredPermissionResourceDeclaration" } ] }, diff --git a/electron/plugins/hostService.cjs b/electron/plugins/hostService.cjs index b3260870d..d27abf5eb 100644 --- a/electron/plugins/hostService.cjs +++ b/electron/plugins/hostService.cjs @@ -19,7 +19,11 @@ const { PluginManager } = require("./pluginManager.cjs"); const { PluginNetworkBroker } = require("./networkBroker.cjs"); const { PluginPermissionEngine } = require("./permissionEngine.cjs"); const { PluginProtocol } = require("./pluginProtocol.cjs"); -const { RuntimeSupervisor, assertStorageParams } = require("./runtimeSupervisor.cjs"); +const { + RuntimeSupervisor, + assertStorageParams, + resolveDefaultRuntimeKind, +} = require("./runtimeSupervisor.cjs"); const { PluginQuotaManager } = require("./quotaManager.cjs"); const { registerSecurePluginCapabilities } = require("./secureCapabilities.cjs"); const { PluginSecretStore } = require("./secretStore.cjs"); @@ -111,9 +115,7 @@ function createPluginHostService(options) { if (configuredRegistry && typeof configuredRegistry.then === "function") { throw new TypeError("Plugin host RPC registry configuration must be synchronous"); } - const requestedRuntimeResolver = options.resolveRuntimeKind ?? (({ plugin }) => ( - plugin.manifest.main.browser ? "browser" : "utility" - )); + const requestedRuntimeResolver = options.resolveRuntimeKind ?? resolveDefaultRuntimeKind; const resolveRuntimeKind = async (context) => { const kind = await requestedRuntimeResolver(context); if ( diff --git a/electron/plugins/hostService.test.cjs b/electron/plugins/hostService.test.cjs index 183f4dede..6e75d1c04 100644 --- a/electron/plugins/hostService.test.cjs +++ b/electron/plugins/hostService.test.cjs @@ -139,6 +139,54 @@ test("runtime trust placement precedes required and advanced permission prompts" ]); }); +test("first-party placement selects the utility runtime for companion manifests", async (context) => { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-host-service-")); + context.after(() => fs.rmSync(root, { recursive: true, force: true })); + const requested = []; + const service = createPluginHostService({ + ...createOptions(root), + requestPermissionDecision: async (request) => { + requested.push(request.permission); + return { requestId: request.requestId, decision: "allow", scope: "application" }; + }, + }); + context.after(() => service.manager.shutdown()); + const manifest = { + manifestVersion: 1, + id: "com.example.companion-placement", + name: "companion-placement", + version: "1.0.0", + publisher: "example", + engines: { netcatty: ">=0.0.0", api: ">=0.1.0-internal <0.2.0" }, + main: { browser: "browser.js", node: "node.js" }, + permissions: { + required: [ + "runtime.advanced", + { + permission: "companion.execute", + resources: ["com.example.companion-placement.helper"], + }, + ], + }, + companionExecutables: [{ + id: "com.example.companion-placement.helper", + variants: [{ + path: "bin/helper", + platforms: [`${process.platform}-${process.arch}`], + sha256: "0".repeat(64), + }], + }], + }; + + assert.equal(await service.runtimeSupervisor.resolveRuntimeKind({ + plugin: { id: manifest.id, activeVersion: manifest.version, manifest }, + availableKinds: ["browser", "utility"], + securityPrincipal: "unsigned-package:companion-placement", + signal: new AbortController().signal, + }), "utility"); + assert.deepEqual(requested, ["companion.execute", "runtime.advanced"]); +}); + test("secure host methods fail closed without an approver while public logging remains available", async (context) => { const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-plugin-host-service-")); context.after(() => fs.rmSync(root, { recursive: true, force: true })); diff --git a/electron/plugins/permissionEngine.test.cjs b/electron/plugins/permissionEngine.test.cjs index 2a2db4cfc..eebb6b6f4 100644 --- a/electron/plugins/permissionEngine.test.cjs +++ b/electron/plugins/permissionEngine.test.cjs @@ -447,7 +447,7 @@ test("session grants require a host-owned session identifier", async (context) = database.close(); }); -test("required preflight rejects resource-scoped permissions without activation bounds", async (context) => { +test("required preflight rejects missing or wildcard resource-scoped activation bounds", async (context) => { const database = createDatabase(context); const requested = []; const engine = new PluginPermissionEngine({ @@ -463,6 +463,12 @@ test("required preflight rejects resource-scoped permissions without activation activeVersion: pluginManifest.version, manifest: pluginManifest, }), /must declare resources/u); + const wildcardManifest = manifest({ required: [{ permission: "network", resources: ["*"] }] }); + await assert.rejects(engine.authorizeRequired({ + id: wildcardManifest.id, + activeVersion: wildcardManifest.version, + manifest: wildcardManifest, + }), /must not use wildcard resources/u); assert.deepEqual(requested, []); database.close(); }); diff --git a/electron/plugins/permissionResources.cjs b/electron/plugins/permissionResources.cjs index 5da261445..3b55e430d 100644 --- a/electron/plugins/permissionResources.cjs +++ b/electron/plugins/permissionResources.cjs @@ -6,12 +6,9 @@ const path = require("node:path"); const contractSchema = require("./generated/plugin-contract.schema.json"); const PLUGIN_PERMISSIONS = new Set(contractSchema.$defs.PluginPermission.enum); -const RESOURCE_SCOPED_PERMISSIONS = new Set([ - "network", - "filesystem.read", - "filesystem.write", - "companion.execute", -]); +const RESOURCE_SCOPED_PERMISSIONS = new Set( + contractSchema.$defs.ResourceScopedPermission.enum, +); function assertPluginPermission(permission) { if (!PLUGIN_PERMISSIONS.has(permission)) { @@ -115,8 +112,13 @@ function normalizePermissionDeclarations(manifest) { : [...new Set((value.resources ?? []).map((resource) => ( canonicalizePermissionResource(permission, resource) )))].sort(); - if (required && RESOURCE_SCOPED_PERMISSIONS.has(permission) && resources.length === 0) { - throw new TypeError(`Required permission ${permission} must declare resources`); + if (required && RESOURCE_SCOPED_PERMISSIONS.has(permission)) { + if (resources.length === 0) { + throw new TypeError(`Required permission ${permission} must declare resources`); + } + if (resources.includes("*")) { + throw new TypeError(`Required permission ${permission} must not use wildcard resources`); + } } declarations.set(permission, Object.freeze({ permission, diff --git a/electron/plugins/runtimeSupervisor.cjs b/electron/plugins/runtimeSupervisor.cjs index d044431b0..372f559b9 100644 --- a/electron/plugins/runtimeSupervisor.cjs +++ b/electron/plugins/runtimeSupervisor.cjs @@ -42,6 +42,11 @@ function freezeJson(value) { return Object.freeze(value); } +function resolveDefaultRuntimeKind({ plugin }) { + if (plugin.manifest.companionExecutables?.length) return "utility"; + return plugin.manifest.main.browser ? "browser" : "utility"; +} + class RuntimeSupervisor { constructor(options) { this.electron = options.electron; @@ -62,9 +67,7 @@ class RuntimeSupervisor { if (this.runtimeMessageGuard != null && typeof this.runtimeMessageGuard !== "function") { throw new TypeError("Plugin runtime message guard must be a function"); } - this.resolveRuntimeKind = options.resolveRuntimeKind ?? (({ plugin }) => ( - plugin.manifest.main.browser ? "browser" : "utility" - )); + this.resolveRuntimeKind = options.resolveRuntimeKind ?? resolveDefaultRuntimeKind; this.resolveSecurityPrincipal = options.resolveSecurityPrincipal ?? (({ plugin }) => defaultSecurityPrincipal(plugin.manifest, plugin.archiveSha256)); if (typeof this.resolveRuntimeKind !== "function" || typeof this.resolveSecurityPrincipal !== "function") { @@ -631,4 +634,9 @@ class RuntimeSupervisor { } } -module.exports = { RuntimeSupervisor, assertStorageParams, freezeJson }; +module.exports = { + RuntimeSupervisor, + assertStorageParams, + freezeJson, + resolveDefaultRuntimeKind, +}; diff --git a/packages/plugin-cli/src/cli.test.ts b/packages/plugin-cli/src/cli.test.ts index 189ec7e3a..5816166ba 100644 --- a/packages/plugin-cli/src/cli.test.ts +++ b/packages/plugin-cli/src/cli.test.ts @@ -238,6 +238,12 @@ test("resource-scoped required permissions must declare activation-time bounds", })); assert.equal(bounded.valid, true, bounded.errors.join("\n")); + const wildcard = validateManifestValue(manifest({ + permissions: { required: [{ permission, resources: ["*"] }] }, + })); + assert.equal(wildcard.valid, false, permission); + assert.match(wildcard.errors.join("\n"), /must not use the wildcard resource/u); + const optional = validateManifestValue(manifest({ permissions: { optional: [permission] }, })); @@ -252,9 +258,9 @@ test("manifest validation applies the runtime resource limit for each permission ["companion.execute", 193, 192], ] as const) { const result = validateManifestValue(manifest({ - permissions: { - required: [{ permission, resources: ["x".repeat(length)] }], - }, + permissions: permission === "storage" + ? { optional: [{ permission, resources: ["x".repeat(length)] }] } + : { required: [{ permission, resources: ["x".repeat(length)] }] }, })); assert.equal(result.valid, false); assert.match( diff --git a/packages/plugin-cli/src/manifest.ts b/packages/plugin-cli/src/manifest.ts index 409b2d9c4..585ef2179 100644 --- a/packages/plugin-cli/src/manifest.ts +++ b/packages/plugin-cli/src/manifest.ts @@ -32,6 +32,9 @@ interface PluginContractSchema extends Record { readonly maxNodes: number; }; }; + readonly ResourceScopedPermission: { + readonly enum: readonly PluginPermission[]; + }; }; } @@ -140,12 +143,9 @@ function permissionResourceLimit(permission: PluginPermission): number { return 2_048; } -const resourceScopedPermissions = new Set([ - "network", - "filesystem.read", - "filesystem.write", - "companion.execute", -]); +const resourceScopedPermissions = new Set( + contractSchema.$defs.ResourceScopedPermission.enum, +); function validateRequiredPermissionBounds(value: unknown): string[] { if (!value || typeof value !== "object" || Array.isArray(value)) return []; @@ -153,11 +153,22 @@ function validateRequiredPermissionBounds(value: unknown): string[] { if (!permissions || typeof permissions !== "object" || Array.isArray(permissions)) return []; const required = (permissions as { required?: unknown }).required; if (!Array.isArray(required)) return []; - return required.flatMap((declaration) => ( - typeof declaration === "string" && resourceScopedPermissions.has(declaration as PluginPermission) - ? [`Required permission ${declaration} must declare explicit resources`] - : [] - )); + return required.flatMap((declaration) => { + if (typeof declaration === "string") { + return resourceScopedPermissions.has(declaration as PluginPermission) + ? [`Required permission ${declaration} must declare explicit resources`] + : []; + } + if (!declaration || typeof declaration !== "object" || Array.isArray(declaration)) return []; + const permission = (declaration as { permission?: unknown }).permission; + const resources = (declaration as { resources?: unknown }).resources; + return typeof permission === "string" + && resourceScopedPermissions.has(permission as PluginPermission) + && Array.isArray(resources) + && resources.includes("*") + ? [`Required permission ${permission} must not use the wildcard resource`] + : []; + }); } function validatePermissionResourceLimits(manifest: PluginManifest): string[] { diff --git a/packages/plugin-contract/schema/plugin-contract.schema.json b/packages/plugin-contract/schema/plugin-contract.schema.json index 5df67c4a7..a4e41bfe2 100644 --- a/packages/plugin-contract/schema/plugin-contract.schema.json +++ b/packages/plugin-contract/schema/plugin-contract.schema.json @@ -237,12 +237,29 @@ "provider.importer" ] }, + "ResourceScopedPermission": { + "description": "A permission whose approval must be constrained to explicit canonical resources.", + "type": "string", + "enum": [ + "network", + "filesystem.read", + "filesystem.write", + "companion.execute" + ] + }, "PermissionResource": { "description": "A host-canonicalized permission resource. Filesystem resources may be absolute platform paths; other permission kinds impose narrower runtime limits.", "type": "string", "minLength": 1, "maxLength": 8192 }, + "BoundedPermissionResource": { + "description": "An explicit resource bound; the all-resources wildcard is not an activation-time bound.", + "type": "string", + "minLength": 1, + "maxLength": 8192, + "not": { "const": "*" } + }, "PermissionResourceKind": { "description": "Whether a canonical resource grant covers only that resource or a filesystem directory subtree.", "type": "string", @@ -270,11 +287,27 @@ { "$ref": "#/$defs/PermissionResourceDeclaration" } ] }, + "RequiredPermissionResourceDeclaration": { + "type": "object", + "required": ["permission", "resources"], + "properties": { + "permission": { "$ref": "#/$defs/ResourceScopedPermission" }, + "resources": { + "type": "array", + "minItems": 1, + "maxItems": 128, + "uniqueItems": true, + "items": { "$ref": "#/$defs/BoundedPermissionResource" } + }, + "reason": { "type": "string", "maxLength": 1024 } + }, + "additionalProperties": false + }, "RequiredPermissionDeclaration": { "description": "Required resource-scoped permissions must name their complete activation-time approval bounds.", "oneOf": [ { "$ref": "#/$defs/NonResourceScopedPermission" }, - { "$ref": "#/$defs/PermissionResourceDeclaration" } + { "$ref": "#/$defs/RequiredPermissionResourceDeclaration" } ] }, "PermissionSet": { diff --git a/packages/plugin-contract/src/contract.test.ts b/packages/plugin-contract/src/contract.test.ts index d983dc76a..343d4e481 100644 --- a/packages/plugin-contract/src/contract.test.ts +++ b/packages/plugin-contract/src/contract.test.ts @@ -67,6 +67,11 @@ test("required resource-scoped permissions declare activation-time bounds", () = ["filesystem.write", "/tmp/plugin-write"], ["companion.execute", "com.example.contract-test.helper"], ] as const; + assert.deepEqual( + schema.$defs.ResourceScopedPermission.enum, + resourceScoped.map(([permission]) => permission), + "the resource-scoped permission catalog must track every bounded permission", + ); assert.deepEqual( schema.$defs.NonResourceScopedPermission.enum, schema.$defs.PluginPermission.enum.filter( @@ -83,6 +88,10 @@ test("required resource-scoped permissions declare activation-time bounds", () = ...validManifest, permissions: { required: [{ permission, resources: [resource] }] }, }), true, JSON.stringify(validate.errors)); + assert.equal(validate({ + ...validManifest, + permissions: { required: [{ permission, resources: ["*"] }] }, + }), false, `${permission} must not accept a wildcard activation bound`); assert.equal(validate({ ...validManifest, permissions: { optional: [permission] }, diff --git a/packages/plugin-contract/src/generated/plugin-contract.ts b/packages/plugin-contract/src/generated/plugin-contract.ts index 8ab92f294..9c319f083 100644 --- a/packages/plugin-contract/src/generated/plugin-contract.ts +++ b/packages/plugin-contract/src/generated/plugin-contract.ts @@ -4,6 +4,8 @@ export type ActivationEvent = "onStartupFinished" | `onCommand:${ContributionId}` | `onView:${ContributionId}` | `onProvider:${ContributionId}`; +export type BoundedPermissionResource = string; + export type CommandContribution = { id: ContributionId; title: LocalizedText; @@ -261,7 +263,15 @@ export type ProviderResult = ({ export type RelativePackagePath = string; -export type RequiredPermissionDeclaration = (NonResourceScopedPermission) | (PermissionResourceDeclaration); +export type RequiredPermissionDeclaration = (NonResourceScopedPermission) | (RequiredPermissionResourceDeclaration); + +export type RequiredPermissionResourceDeclaration = { + permission: ResourceScopedPermission; + resources: Array; + reason?: string; +}; + +export type ResourceScopedPermission = "network" | "filesystem.read" | "filesystem.write" | "companion.execute"; export type RpcCancel = { jsonrpc: "2.0";