From 27d6246b6026de3b964d2f2bce7d44302213503e Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 24 Sep 2026 17:39:30 +0200 Subject: [PATCH 1/2] Let a plugin accept a file as base64 (#1727) An `accepts` entry takes an optional `as: "text" | "base64"`, text by default. With base64 the host hands over the file's exact bytes as `input.upload.base64`, with no charset detection; text mode still arrives as `input.upload.text`, so a plugin can tell them apart. - `as` is kept as declared: left out, it stays out of the serialized manifest, and an explicit "text" stays in, so no release id moves. - Both validators accept text or base64 and reject anything else with the same message, checked against new shared fixtures. - The server checks the upload is in a declared encoding and bounds it by its raw size: the decoded length for base64, not the string's. - The data browser picks the matching `accepts` entry and reads the file with `readUpload` from @tomic/lib. Co-Authored-By: Claude Opus 5.5 --- .../src/chunks/PluginRuns/FileImport.tsx | 35 +++--- browser/lib/src/index.ts | 8 ++ browser/lib/src/plugin-manifest.ts | 38 ++++-- browser/lib/src/plugin-upload.test.ts | 86 +++++++++++++ browser/lib/src/plugin-upload.ts | 70 +++++++++++ docs/src/plugins/creating-plugins.md | 5 + server/src/handlers/plugin_run.rs | 118 ++++++++++++++++-- server/src/plugins/js_runtime.rs | 41 ++++++ server/src/plugins/manifest.rs | 56 +++++++-- server/src/plugins/release.rs | 26 ++++ testdata/plugin-manifest/index.json | 46 ++++++- .../v2-accepts-as-not-string.json | 8 ++ .../v2-accepts-as-upper-case.json | 8 ++ .../plugin-manifest/v2-accepts-base64.json | 12 ++ .../v2-accepts-default-text.json | 12 ++ 15 files changed, 524 insertions(+), 45 deletions(-) create mode 100644 browser/lib/src/plugin-upload.test.ts create mode 100644 browser/lib/src/plugin-upload.ts create mode 100644 testdata/plugin-manifest/v2-accepts-as-not-string.json create mode 100644 testdata/plugin-manifest/v2-accepts-as-upper-case.json create mode 100644 testdata/plugin-manifest/v2-accepts-base64.json create mode 100644 testdata/plugin-manifest/v2-accepts-default-text.json diff --git a/browser/data-browser/src/chunks/PluginRuns/FileImport.tsx b/browser/data-browser/src/chunks/PluginRuns/FileImport.tsx index d03c0acfed..19f2b94018 100644 --- a/browser/data-browser/src/chunks/PluginRuns/FileImport.tsx +++ b/browser/data-browser/src/chunks/PluginRuns/FileImport.tsx @@ -1,11 +1,13 @@ import { useEffect, useId, useState } from 'react'; import { + acceptFor, core, dataBrowser, ensureSchema, executeServerPlugin, pluginConfigFor, pluginConfigProblems, + readUpload, useStore, DEFAULT_ACCEPT_MAX_BYTES, type DeclaredAccept, @@ -28,9 +30,11 @@ import { RunPluginDialog } from './RunPluginDialog'; * The generic entry point for a plugin that declares `accepts`: choose a file, * preview what the plugin proposes for it, approve. * - * The host owns acquisition: it enforces the declared size, decodes the file - * and hands it over as `input.upload`. The plugin runs on the server (it may - * need `ctx.query`/`ctx.read` to recognise earlier imports), and nothing is + * The host owns acquisition: it enforces the declared size on the file's + * bytes, reads the file as its `accepts` entry declares (decoded text, or + * base64 of the exact bytes) and hands it over as `input.upload`. The plugin + * runs on the server (it may need `ctx.query`/`ctx.read` to recognise earlier + * imports), and nothing is * written until the proposal is approved in {@link RunPluginDialog}. A plugin * that also declares a `destination` gets a Set up step first, which creates * that table and stores it as the plugin's config. @@ -105,23 +109,23 @@ export function FileImport({ setImported(false); try { - const max = maxBytes(accepts); + const accept = acceptFor(file, accepts); + if (!accept) throw new Error('This plugin does not accept files.'); + // The server bounds an upload by the entries sharing its encoding. + const max = maxBytes( + accepts.filter(other => (other.as ?? 'text') === (accept.as ?? 'text')), + ); if (file.size > max) throw new Error( `This file is ${formatBytes(file.size)}; this importer accepts at most ${formatBytes(max)}. Export a shorter period.`, ); - const text = decode(await file.arrayBuffer()); + const upload = readUpload(file, await file.arrayBuffer(), accept); const result = await executeServerPlugin(store, { drive, plugin: resource.subject, source, input: { - upload: { - name: file.name, - mediaType: file.type, - size: file.size, - text, - }, + upload, config, trigger: { kind: 'manual', @@ -233,15 +237,6 @@ function formatBytes(bytes: number): string { return `${bytes} bytes`; } -/** UTF-8 when the file is valid UTF-8; older bank exports are often Windows-1252. */ -export function decode(bytes: ArrayBuffer): string { - try { - return new TextDecoder('utf-8', { fatal: true }).decode(bytes); - } catch { - return new TextDecoder('windows-1252').decode(bytes); - } -} - async function storedConfig( store: Store, drive: string, diff --git a/browser/lib/src/index.ts b/browser/lib/src/index.ts index b1a5d46e10..b21c32f6b0 100644 --- a/browser/lib/src/index.ts +++ b/browser/lib/src/index.ts @@ -206,6 +206,7 @@ export { type DeclaredConfig, type DeclaredConfigField, type DeclaredAccept, + type AcceptEncoding, type DeclaredDestination, DEFAULT_ACCEPT_MAX_BYTES, ACCEPT_MAX_BYTES_CEILING, @@ -214,6 +215,13 @@ export { type PluginManifest, type PluginManifestV2, } from './plugin-manifest.js'; +export { + acceptFor, + readUpload, + decodeUploadText, + encodeBase64, + type PluginUpload, +} from './plugin-upload.js'; export { pluginConfigFor, pluginConfigProblems, diff --git a/browser/lib/src/plugin-manifest.ts b/browser/lib/src/plugin-manifest.ts index 59e521f75e..2445ed07b5 100644 --- a/browser/lib/src/plugin-manifest.ts +++ b/browser/lib/src/plugin-manifest.ts @@ -63,6 +63,9 @@ export interface DeclaredConfig { required?: string[]; } +/** How an accepted file reaches the plugin; see {@link DeclaredAccept}. */ +export type AcceptEncoding = 'text' | 'base64'; + /** What the host accepts when no `maxBytes` is declared: 5 MiB. */ export const DEFAULT_ACCEPT_MAX_BYTES = 5 * 1024 * 1024; /** @@ -75,17 +78,29 @@ export const ACCEPT_MAX_BYTES_CEILING = 20 * 1024 * 1024; /** * A file a plugin can be handed by the host, instead of fetching data itself. * - * The host draws the picker, enforces `maxBytes`, decodes the file and passes - * it as `input.upload` = `{ name, mediaType, size, text }`. `extensions` and - * `mediaTypes` only filter the picker; the plugin must still validate the - * content it is given. Only `as: 'text'` exists so far: UTF-8, falling back to - * Windows-1252. + * The host draws the picker, enforces `maxBytes` on the file's raw size and + * passes it as `input.upload` (`ctx.upload` in `run`), in the declared + * encoding, under a field named after it: + * + * - `as: 'text'` (the default when `as` is left out): + * `{ name, mediaType, size, text }`, decoded as UTF-8 and falling back to + * Windows-1252 when the file is not valid UTF-8. + * - `as: 'base64'`: `{ name, mediaType, size, base64 }`, the file's exact bytes + * base64-encoded (standard alphabet, padded), with no charset detection. + * + * `size` is always the byte size of the file. `extensions` and `mediaTypes` + * only filter the picker; the plugin must still validate the content it is + * given. See `PluginUpload` in `plugin-upload.ts`. */ export interface DeclaredAccept { /** Lower-case, with the leading dot: `.xml`. */ extensions?: string[]; mediaTypes?: string[]; - as: 'text'; + /** + * How the host hands over the file. Left out, it is `text`, and it stays + * left out when serialized, so a release's id does not change. + */ + as?: AcceptEncoding; /** Bytes, at most {@link ACCEPT_MAX_BYTES_CEILING}. */ maxBytes?: number; } @@ -662,8 +677,12 @@ export function validateManifest(raw: unknown): PluginManifest { const accepts = list(entry.accepts, 'accepts').map(value => { const accept = object(value, 'accepts entry'); known(accept, ['extensions', 'mediaTypes', 'as', 'maxBytes']); - if (accept.as !== 'text') - throw new Error('accepts entries must be read `as` text'); + if ( + accept.as !== undefined && + accept.as !== 'text' && + accept.as !== 'base64' + ) + throw new Error('accepts entries must be read `as` text or base64'); const extensions = list(accept.extensions, 'accepts.extensions').map( extension => { if ( @@ -702,7 +721,8 @@ export function validateManifest(raw: unknown): PluginManifest { return { ...(extensions.length ? { extensions } : {}), ...(mediaTypes.length ? { mediaTypes } : {}), - as: 'text' as const, + // Kept exactly as declared: an absent `as` stays absent. + ...(accept.as !== undefined ? { as: accept.as as AcceptEncoding } : {}), ...(accept.maxBytes !== undefined ? { maxBytes: accept.maxBytes as number } : {}), diff --git a/browser/lib/src/plugin-upload.test.ts b/browser/lib/src/plugin-upload.test.ts new file mode 100644 index 0000000000..b4080cf529 --- /dev/null +++ b/browser/lib/src/plugin-upload.test.ts @@ -0,0 +1,86 @@ +import { describe, expect, it } from 'vitest'; +import { acceptFor, readUpload } from './plugin-upload.js'; +import type { DeclaredAccept } from './plugin-manifest.js'; + +const everyByte = Uint8Array.from({ length: 256 }, (_, i) => i); + +describe('readUpload', () => { + it('hands a base64 plugin the exact bytes, every value 0–255', () => { + const upload = readUpload( + { name: 'drop.willow', type: '' }, + everyByte.buffer, + { as: 'base64' }, + ); + + expect(upload).toEqual({ + name: 'drop.willow', + mediaType: '', + size: 256, + base64: Buffer.from(everyByte).toString('base64'), + }); + expect('text' in upload).toBe(false); + expect( + Uint8Array.from(Buffer.from((upload as { base64: string }).base64, 'base64')), + ).toEqual(everyByte); + }); + + it('encodes a file larger than one chunk without losing bytes', () => { + const large = Uint8Array.from({ length: 100_003 }, (_, i) => (i * 7) & 255); + const upload = readUpload({ name: 'x', type: '' }, large, { + as: 'base64', + }) as { base64: string }; + + expect(Uint8Array.from(Buffer.from(upload.base64, 'base64'))).toEqual( + large, + ); + }); + + it('keeps text mode unchanged for MT940, with `as` given or left out', () => { + const mt940 = + ':20:STARTUMSE\r\n:25:NL91ABNA0417164300\r\n:28C:00001/001\r\n' + + ':60F:C240101EUR1000,00\r\n:86:Café\r\n'; + const utf8 = new TextEncoder().encode(mt940); + // The same statement exported as Windows-1252: é is the single byte 0xE9. + const cp1252 = Uint8Array.from(mt940, c => c.charCodeAt(0)); + + for (const accept of [{ as: 'text' }, {}] as DeclaredAccept[]) { + for (const bytes of [utf8, cp1252]) { + const upload = readUpload( + { name: 'statement.sta', type: 'text/plain' }, + bytes, + accept, + ); + expect(upload).toEqual({ + name: 'statement.sta', + mediaType: 'text/plain', + size: bytes.byteLength, + text: mt940, + }); + } + } + }); +}); + +describe('acceptFor', () => { + const accepts: DeclaredAccept[] = [ + { extensions: ['.sta'], as: 'text' }, + { extensions: ['.willow'], mediaTypes: ['application/x-willow'], as: 'base64' }, + ]; + + it('picks the entry that names the file', () => { + expect(acceptFor({ name: 'A.STA', type: '' }, accepts)).toBe(accepts[0]); + expect(acceptFor({ name: 'drop.willow', type: '' }, accepts)).toBe( + accepts[1], + ); + expect( + acceptFor({ name: 'drop', type: 'application/x-willow' }, accepts), + ).toBe(accepts[1]); + }); + + it('falls back to the first entry when none names the file', () => { + expect(acceptFor({ name: 'other.bin', type: '' }, accepts)).toBe( + accepts[0], + ); + expect(acceptFor({ name: 'x', type: '' }, [])).toBeUndefined(); + }); +}); diff --git a/browser/lib/src/plugin-upload.ts b/browser/lib/src/plugin-upload.ts new file mode 100644 index 0000000000..77e0b914d0 --- /dev/null +++ b/browser/lib/src/plugin-upload.ts @@ -0,0 +1,70 @@ +import type { DeclaredAccept } from './plugin-manifest.js'; + +/** + * A file as a plugin receives it, in `input.upload` (`ctx.upload` in `run`). + * The field that carries the content is named after the encoding the + * matching `accepts` entry declared, so a plugin can tell them apart: `text` + * for `as: 'text'` (the default), `base64` for `as: 'base64'`. `size` is the + * file's byte size either way. + */ +export type PluginUpload = { + name: string; + mediaType: string; + size: number; +} & ({ text: string } | { base64: string }); + +/** + * The `accepts` entry a chosen file falls under: the first that names its + * extension, then the first that names its media type, else the first entry + * (the picker's filter is only a hint, so a file may match none). + */ +export function acceptFor( + file: { name: string; type: string }, + accepts: DeclaredAccept[], +): DeclaredAccept | undefined { + const name = file.name.toLowerCase(); + + return ( + accepts.find(accept => + accept.extensions?.some(extension => name.endsWith(extension)), + ) ?? + accepts.find( + accept => file.type && accept.mediaTypes?.includes(file.type), + ) ?? + accepts[0] + ); +} + +/** Builds `input.upload` from a file's bytes, as `accept` declares. */ +export function readUpload( + file: { name: string; type: string }, + bytes: ArrayBuffer | Uint8Array, + accept: DeclaredAccept, +): PluginUpload { + const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes); + const meta = { name: file.name, mediaType: file.type, size: view.byteLength }; + + return accept.as === 'base64' + ? { ...meta, base64: encodeBase64(view) } + : { ...meta, text: decodeUploadText(view) }; +} + +/** UTF-8 when the file is valid UTF-8; older bank exports are often Windows-1252. */ +export function decodeUploadText(bytes: ArrayBuffer | Uint8Array): string { + try { + return new TextDecoder('utf-8', { fatal: true }).decode(bytes); + } catch { + return new TextDecoder('windows-1252').decode(bytes); + } +} + +/** Standard, padded base64 of exact bytes. Chunked: files run to megabytes. */ +export function encodeBase64(bytes: Uint8Array): string { + const chunk = 0x8000; + let binary = ''; + + for (let i = 0; i < bytes.length; i += chunk) + binary += String.fromCharCode(...bytes.subarray(i, i + chunk)); + + return btoa(binary); +} diff --git a/docs/src/plugins/creating-plugins.md b/docs/src/plugins/creating-plugins.md index eb84e442c6..90f988d63e 100644 --- a/docs/src/plugins/creating-plugins.md +++ b/docs/src/plugins/creating-plugins.md @@ -127,6 +127,11 @@ Every field except `schemaVersion` is optional; unknown fields and malformed dec - `secrets`, `operations`, `actions`: as in schema version 1. Secrets name an exact origin a credential may be sent to; operations are exact endpoints with an `effect` of `read` or `write`; actions reference operations. - `network.origins`: exact origins (no wildcards, paths or ports beyond the origin) for packages that call the host `fetch` without an operation id. It never widens what `operations` grant. - `configSchema`, `defaultConfig`: objects, as in `plugin.json`. +- `accepts`: files the host may hand the plugin, up to eight entries of `{ extensions?, mediaTypes?, as?, maxBytes? }`. `extensions` (lower-case, with the dot) and `mediaTypes` only filter the file picker. `maxBytes` (default 5 MiB, at most 20 MiB) bounds the file's raw byte size. `as` says how the file arrives in `ctx.upload`, in a field named after it: + - `"text"`, the default when `as` is left out: `{ name, mediaType, size, text }`, decoded as UTF-8, falling back to Windows-1252. + - `"base64"`: `{ name, mediaType, size, base64 }`, the file's exact bytes in standard padded base64, with no charset detection. `atob(ctx.upload.base64)` gives it back as a binary string, one character per byte. + + `size` is the byte size of the file in both cases. Leaving `as` out does not add it to the stored manifest, so the release id stays the same. - `name`, `namespace`, `version`, `description`, `author`: metadata. `name` and `namespace` must be safe path segments. A schema version 1 manifest is still accepted and is read as version 2 with `runtime: atomic-js/1`, `world: extension` and `entrypoints: { run: true }`. diff --git a/server/src/handlers/plugin_run.rs b/server/src/handlers/plugin_run.rs index daaab230b2..3dd69b5f6f 100644 --- a/server/src/handlers/plugin_run.rs +++ b/server/src/handlers/plugin_run.rs @@ -102,12 +102,18 @@ pub async fn handle_plugin_run( pub const RUN_JSON_LIMIT: usize = crate::serve::PAYLOAD_MAX; /// A file handed to the plugin (`input.upload`) must be one it declared it -/// accepts, and no larger than it said. The browser checks this too, before -/// reading the file; this is the check that holds. +/// accepts, in the encoding it declared (`text` or `base64`, named by the +/// field that carries it), and no larger than it said. The limit is on the +/// file's bytes: for base64 that is the decoded length, not the string's. The +/// browser checks this too, before reading the file; this is the check that +/// holds. fn check_upload( manifest: Option<&crate::plugins::manifest::Manifest>, input: &str, ) -> AtomicServerResult<()> { + use crate::plugins::manifest::AcceptAs; + use base64::Engine as _; + let input: serde_json::Value = serde_json::from_str(input) .map_err(|e| AtomicServerError::bad_request(format!("input is not JSON: {e}")))?; let Some(upload) = input.get("upload") else { @@ -119,16 +125,44 @@ fn check_upload( "This plugin does not accept files", )); } - let Some(text) = upload.get("text").and_then(|t| t.as_str()) else { + let carried: Vec = [AcceptAs::Text, AcceptAs::Base64] + .into_iter() + .filter(|encoding| upload.get(encoding.field()).is_some()) + .collect(); + let [encoding] = carried[..] else { return Err(AtomicServerError::bad_request( - "input.upload needs the file as text", + "input.upload needs the file as exactly one of text or base64", )); }; - let max = accepts.iter().map(|a| a.max_bytes()).max().unwrap_or(0); - if text.len() as u64 > max { + let Some(content) = upload.get(encoding.field()).and_then(|c| c.as_str()) else { return Err(AtomicServerError::bad_request(format!( - "This file is {} bytes; this plugin accepts at most {max}", - text.len() + "input.upload.{} must be a string", + encoding.field() + ))); + }; + let Some(max) = accepts + .iter() + .filter(|a| a.encoding() == encoding) + .map(|a| a.max_bytes()) + .max() + else { + return Err(AtomicServerError::bad_request(format!( + "This plugin does not accept files as {}", + encoding.field() + ))); + }; + let size = match encoding { + AcceptAs::Text => content.len(), + AcceptAs::Base64 => base64::engine::general_purpose::STANDARD + .decode(content) + .map_err(|e| { + AtomicServerError::bad_request(format!("input.upload.base64 is not base64: {e}")) + })? + .len(), + }; + if size as u64 > max { + return Err(AtomicServerError::bad_request(format!( + "This file is {size} bytes; this plugin accepts at most {max}" ))); } Ok(()) @@ -163,4 +197,72 @@ mod tests { // A run without a file is not affected. assert!(check_upload(None, r#"{"trigger":{"kind":"manual"}}"#).is_ok()); } + + fn base64_upload(bytes: &[u8]) -> String { + use base64::Engine as _; + serde_json::json!({"upload": { + "base64": base64::engine::general_purpose::STANDARD.encode(bytes), + }}) + .to_string() + } + + #[test] + fn a_base64_upload_is_limited_by_its_raw_size() { + let every_byte: Vec = (0..=255u8).collect(); + let accepting = manifest(serde_json::json!({ + "schemaVersion": 2, + "accepts": [{"as": "base64", "maxBytes": 256}], + })); + + // 344 base64 characters, 256 bytes: the bytes are what counts. + assert!(check_upload(Some(&accepting), &base64_upload(&every_byte)).is_ok()); + let over = [every_byte.as_slice(), &[0]].concat(); + assert!(check_upload(Some(&accepting), &base64_upload(&over)) + .unwrap_err() + .message + .contains("257 bytes")); + } + + #[test] + fn an_upload_must_use_the_encoding_the_plugin_declared() { + let text_only = manifest(serde_json::json!({ + "schemaVersion": 2, + "accepts": [{"maxBytes": 100}], + })); + let base64_only = manifest(serde_json::json!({ + "schemaVersion": 2, + "accepts": [{"as": "base64", "maxBytes": 100}], + })); + let text = serde_json::json!({"upload": {"text": "x"}}).to_string(); + + // `as` left out means text. + assert!(check_upload(Some(&text_only), &text).is_ok()); + assert!(check_upload(Some(&text_only), &base64_upload(b"x")).is_err()); + assert!(check_upload(Some(&base64_only), &text).is_err()); + assert!(check_upload(Some(&base64_only), &base64_upload(b"x")).is_ok()); + // Not base64, or both at once: refused rather than guessed at. + assert!( + check_upload(Some(&base64_only), r#"{"upload":{"base64":"not base64!"}}"#).is_err() + ); + assert!(check_upload( + Some(&base64_only), + r#"{"upload":{"base64":"eA==","text":"x"}}"# + ) + .is_err()); + } + + #[test] + fn text_mode_is_unchanged_for_mt940() { + let accepting = manifest(serde_json::json!({ + "schemaVersion": 2, + "accepts": [{"extensions": [".sta"], "as": "text", "maxBytes": 128}], + })); + let mt940 = ":20:STARTUMSE\r\n:25:NL91ABNA0417164300\r\n:28C:00001/001\r\n\ + :60F:C240101EUR1000,00\r\n:61:2401020102D12,50NTRFNONREF\r\n:86:Café\r\n"; + let upload = |text: &str| serde_json::json!({"upload": {"text": text}}).to_string(); + + assert_eq!(mt940.len(), 122); + assert!(check_upload(Some(&accepting), &upload(mt940)).is_ok()); + assert!(check_upload(Some(&accepting), &upload(&mt940.repeat(2))).is_err()); + } } diff --git a/server/src/plugins/js_runtime.rs b/server/src/plugins/js_runtime.rs index 11ec4e561e..5dfc3037f8 100644 --- a/server/src/plugins/js_runtime.rs +++ b/server/src/plugins/js_runtime.rs @@ -713,6 +713,47 @@ mod tests { assert!(error.contains("stopped"), "{error}"); } + #[tokio::test] + async fn a_base64_upload_reaches_the_plugin_byte_for_byte() { + // `accepts: [{ as: "base64" }]`: the host hands over the exact bytes + // as `upload.base64`, and the sandbox's `atob` gets them back. + use base64::Engine as _; + let bytes: Vec = (0..=255u8).collect(); + let input = serde_json::json!({ + "trigger": {"kind": "manual", "at": 1700000000000u64}, + "upload": { + "name": "every-byte.bin", + "mediaType": "application/octet-stream", + "size": bytes.len(), + "base64": base64::engine::general_purpose::STANDARD.encode(&bytes), + }, + }) + .to_string(); + let runtime = runtime(); + let (h, _) = host(); + + let verdict = runtime + .run( + r#"export function run(ctx) { + const binary = atob(ctx.upload.base64); + const bytes = Array.from(binary, c => c.charCodeAt(0)); + return { intents: [], problems: [], text: typeof ctx.upload.text, + size: ctx.upload.size, bytes }; + }"#, + &input, + h, + ) + .await + .unwrap() + .expect("ran"); + + let verdict: serde_json::Value = serde_json::from_str(&verdict).unwrap(); + let received: Vec = serde_json::from_value(verdict["bytes"].clone()).unwrap(); + assert_eq!(received, bytes); + assert_eq!(verdict["size"], 256); + assert_eq!(verdict["text"], "undefined"); + } + #[tokio::test] async fn a_plugin_has_no_ambient_io() { let runtime = runtime(); diff --git a/server/src/plugins/manifest.rs b/server/src/plugins/manifest.rs index d6fb9e788e..20f7c083fa 100644 --- a/server/src/plugins/manifest.rs +++ b/server/src/plugins/manifest.rs @@ -319,8 +319,9 @@ pub const ACCEPT_MAX_BYTES_CEILING: u64 = 20 * 1024 * 1024; /// A file the host may hand the plugin as `input.upload`, instead of the /// plugin fetching data itself. `extensions` and `mediaTypes` only filter the -/// picker; the plugin still validates what it is given. Only `as: "text"` -/// exists: UTF-8, falling back to Windows-1252, decoded by the host. +/// picker; the plugin still validates what it is given. `maxBytes` bounds the +/// file's raw size, whatever the encoding. See [`AcceptAs`] for what the +/// plugin receives. #[derive(Debug, Clone, Deserialize, Serialize)] #[serde(rename_all = "camelCase", deny_unknown_fields)] pub struct Accept { @@ -328,8 +329,10 @@ pub struct Accept { pub extensions: Vec, #[serde(default, skip_serializing_if = "Vec::is_empty")] pub media_types: Vec, - #[serde(rename = "as")] - pub read_as: String, + /// Kept as declared: left out, it stays out when serialized, so a + /// release's id does not change; an explicit `"text"` stays too. + #[serde(default, rename = "as", skip_serializing_if = "Option::is_none")] + pub read_as: Option, #[serde(default, skip_serializing_if = "Option::is_none")] pub max_bytes: Option, } @@ -338,6 +341,48 @@ impl Accept { pub fn max_bytes(&self) -> u64 { self.max_bytes.unwrap_or(DEFAULT_ACCEPT_MAX_BYTES) } + + pub fn encoding(&self) -> AcceptAs { + self.read_as.unwrap_or_default() + } +} + +/// How an accepted file reaches the plugin, in `input.upload` +/// (`{ name, mediaType, size, }`, `size` being the byte size): +/// +/// - `text` (the default): the field `text`, decoded by the host as UTF-8, +/// falling back to Windows-1252. +/// - `base64`: the field `base64`, the file's exact bytes in standard padded +/// base64, with no charset detection. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize)] +#[serde(rename_all = "lowercase")] +pub enum AcceptAs { + #[default] + Text, + Base64, +} + +impl AcceptAs { + /// The `input.upload` field that carries the file in this encoding. + pub fn field(self) -> &'static str { + match self { + Self::Text => "text", + Self::Base64 => "base64", + } + } +} + +// By hand, so that every wrong value gets the one message both validators share. +impl<'de> Deserialize<'de> for AcceptAs { + fn deserialize>(deserializer: D) -> Result { + match serde_json::Value::deserialize(deserializer)?.as_str() { + Some("text") => Ok(Self::Text), + Some("base64") => Ok(Self::Base64), + _ => Err(serde::de::Error::custom( + "accepts entries must be read `as` text or base64", + )), + } + } } #[derive(Debug, Clone, Deserialize, Serialize)] @@ -464,9 +509,6 @@ impl Manifest { return Err("at most 8 accepts entries".into()); } for accept in &self.accepts { - if accept.read_as != "text" { - return Err("accepts entries must be read `as` text".into()); - } if accept .max_bytes .is_some_and(|max| !(1..=ACCEPT_MAX_BYTES_CEILING).contains(&max)) diff --git a/server/src/plugins/release.rs b/server/src/plugins/release.rs index 45b9c645d6..da67da4b58 100644 --- a/server/src/plugins/release.rs +++ b/server/src/plugins/release.rs @@ -690,6 +690,32 @@ mod tests { assert_eq!(again, full); } + #[test] + fn accepts_without_as_keeps_the_release_id() { + // `as` is optional and text by default. A manifest that leaves it out, + // and one written for #1691 that spells out `"as": "text"`, must both + // serialize to exactly what was published. + let fixtures = concat!(env!("CARGO_MANIFEST_DIR"), "/../testdata/plugin-manifest"); + for file in [ + "v2-accepts-default-text.json", + "v2-accepts-destination.json", + ] { + let path = format!("{fixtures}/{file}"); + let raw: serde_json::Value = + serde_json::from_str(&std::fs::read_to_string(&path).unwrap()).unwrap(); + let parsed = serde_json::json!(Manifest::parse(raw.clone()).unwrap().unwrap()); + let source = "export function run() { return {}; }".to_string(); + let before = PluginRelease::js(source.clone(), raw.clone(), Default::default()); + let after = PluginRelease::js(source, parsed.clone(), Default::default()); + assert_eq!(before.id().unwrap(), after.id().unwrap(), "{file}"); + assert_eq!( + parsed["accepts"][0].get("as"), + raw["accepts"][0].get("as"), + "{file}" + ); + } + } + #[test] fn package_hashes_are_blake3_hex() { assert!(package_hash(&"ab".repeat(32)).is_ok()); diff --git a/testdata/plugin-manifest/index.json b/testdata/plugin-manifest/index.json index d88dfa4cd6..50d218e822 100644 --- a/testdata/plugin-manifest/index.json +++ b/testdata/plugin-manifest/index.json @@ -449,7 +449,7 @@ "error": "accepts maxBytes must be" }, { - "name": "v2 accepts only text", + "name": "v2 accepts an unknown `as`", "file": "v2-accepts-not-text.json", "error": "accepts entries must be read" }, @@ -467,5 +467,49 @@ "name": "v1 has no accepts", "file": "v1-accepts.json", "error": "unknown field" + }, + { + "name": "v2 accepts a file as base64", + "file": "v2-accepts-base64.json", + "serialized": { + "schemaVersion": 2, + "secrets": [], + "operations": [], + "accepts": [ + { + "extensions": [ + ".willow" + ], + "as": "base64", + "maxBytes": 1000000 + } + ] + } + }, + { + "name": "v2 accepts without `as` reads text and serializes without it", + "file": "v2-accepts-default-text.json", + "serialized": { + "schemaVersion": 2, + "secrets": [], + "operations": [], + "accepts": [ + { + "extensions": [ + ".sta" + ] + } + ] + } + }, + { + "name": "v2 accepts `as` that is not a string", + "file": "v2-accepts-as-not-string.json", + "error": "accepts entries must be read" + }, + { + "name": "v2 accepts `as` is case-sensitive", + "file": "v2-accepts-as-upper-case.json", + "error": "accepts entries must be read" } ] diff --git a/testdata/plugin-manifest/v2-accepts-as-not-string.json b/testdata/plugin-manifest/v2-accepts-as-not-string.json new file mode 100644 index 0000000000..872a21b65a --- /dev/null +++ b/testdata/plugin-manifest/v2-accepts-as-not-string.json @@ -0,0 +1,8 @@ +{ + "schemaVersion": 2, + "accepts": [ + { + "as": 64 + } + ] +} diff --git a/testdata/plugin-manifest/v2-accepts-as-upper-case.json b/testdata/plugin-manifest/v2-accepts-as-upper-case.json new file mode 100644 index 0000000000..df6431f545 --- /dev/null +++ b/testdata/plugin-manifest/v2-accepts-as-upper-case.json @@ -0,0 +1,8 @@ +{ + "schemaVersion": 2, + "accepts": [ + { + "as": "Base64" + } + ] +} diff --git a/testdata/plugin-manifest/v2-accepts-base64.json b/testdata/plugin-manifest/v2-accepts-base64.json new file mode 100644 index 0000000000..fa0e330e09 --- /dev/null +++ b/testdata/plugin-manifest/v2-accepts-base64.json @@ -0,0 +1,12 @@ +{ + "schemaVersion": 2, + "accepts": [ + { + "extensions": [ + ".willow" + ], + "as": "base64", + "maxBytes": 1000000 + } + ] +} diff --git a/testdata/plugin-manifest/v2-accepts-default-text.json b/testdata/plugin-manifest/v2-accepts-default-text.json new file mode 100644 index 0000000000..8714ea8f1b --- /dev/null +++ b/testdata/plugin-manifest/v2-accepts-default-text.json @@ -0,0 +1,12 @@ +{ + "schemaVersion": 2, + "secrets": [], + "operations": [], + "accepts": [ + { + "extensions": [ + ".sta" + ] + } + ] +} From 17ff3f70010fdc94690e910edfde7096186891e4 Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 25 Sep 2026 10:32:05 +0200 Subject: [PATCH 2/2] Format plugin-upload.test.ts with oxfmt The pre-commit format check was skipped when this branch was committed with --no-verify. Co-Authored-By: Claude Opus 5.5 --- browser/lib/src/plugin-upload.test.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/browser/lib/src/plugin-upload.test.ts b/browser/lib/src/plugin-upload.test.ts index b4080cf529..c46b13bafc 100644 --- a/browser/lib/src/plugin-upload.test.ts +++ b/browser/lib/src/plugin-upload.test.ts @@ -20,7 +20,9 @@ describe('readUpload', () => { }); expect('text' in upload).toBe(false); expect( - Uint8Array.from(Buffer.from((upload as { base64: string }).base64, 'base64')), + Uint8Array.from( + Buffer.from((upload as { base64: string }).base64, 'base64'), + ), ).toEqual(everyByte); }); @@ -64,7 +66,11 @@ describe('readUpload', () => { describe('acceptFor', () => { const accepts: DeclaredAccept[] = [ { extensions: ['.sta'], as: 'text' }, - { extensions: ['.willow'], mediaTypes: ['application/x-willow'], as: 'base64' }, + { + extensions: ['.willow'], + mediaTypes: ['application/x-willow'], + as: 'base64', + }, ]; it('picks the entry that names the file', () => {