OxygenHub 0.9.19: attachments on issues and comments, over the API and oh --attach; images by their bytes shown in place, everything else a download (closes #350) 1c52d940b4a0

-- Files attached to issues, comments and proposals (oxygenhub#350): kept by

-- content in the hub's assets store, as release assets are, and served

-- under the repository's read rules.

CREATE TABLE attachments (

    id           BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,

    repo_id      BIGINT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,

    name         TEXT NOT NULL,

    size         BIGINT NOT NULL,

    hash         TEXT NOT NULL,

    content_type TEXT NOT NULL,

    uploader_id  BIGINT,

    created_ms   BIGINT NOT NULL

);

CREATE INDEX attachments_repo ON attachments (repo_id);

CREATE INDEX attachments_hash ON attachments (hash);

-- Files attached to issues, comments and proposals (oxygenhub#350): kept by

-- content in the hub's assets store, as release assets are, and served

-- under the repository's read rules.

CREATE TABLE attachments (

    id           INTEGER PRIMARY KEY,

    repo_id      INTEGER NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,

    name         TEXT NOT NULL,

    size         INTEGER NOT NULL,

    hash         TEXT NOT NULL,

    content_type TEXT NOT NULL,

    uploader_id  INTEGER,

    created_ms   INTEGER NOT NULL

);

CREATE INDEX attachments_repo ON attachments (repo_id);

CREATE INDEX attachments_hash ON attachments (hash);

//! Attachments over the API (oxygenhub#350): `POST

//! /api/v1/repos/{owner}/{name}/attachments?name=FILE` with the file's

//! bytes as the body. Anyone signed in who may read the repository and

//! write issues may attach; what comes back says how to show it.

use super::{caller, reach, ApiError};

use crate::auth::roles::Access;

use crate::db;

use crate::Shared;

use axum::body::Bytes;

use axum::extract::{Path, Query, State};

use axum::http::{HeaderMap, StatusCode};

use axum::Json;

/// The largest file one attachment may be.

pub const ATTACHMENT_MAX: usize = 25 << 20;

#[derive(serde::Deserialize)]

pub struct Named {

    name: String,

}

/// An image type a page may show, from the bytes; never what the uploader

/// said (an SVG or HTML file would run in the hub's origin).

pub fn image_type(bytes: &[u8]) -> Option<&'static str> {

    if bytes.starts_with(b"\x89PNG\r\n\x1a\n") {

        Some("image/png")

    } else if bytes.starts_with(&[0xFF, 0xD8, 0xFF]) {

        Some("image/jpeg")

    } else if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") {

        Some("image/gif")

    } else if bytes.len() >= 12 && &bytes[..4] == b"RIFF" && &bytes[8..12] == b"WEBP" {

        Some("image/webp")

    } else {

        None

    }

}

/// A file name to keep: its last part, plain, not hidden.

pub fn file_name(name: &str) -> Option<String> {

    let base = name.rsplit(['/', '\\']).next().unwrap_or(name).trim();

    let clean: String = base.chars().filter(|c| !c.is_control() && !matches!(c, '"' | '<' | '>' | '`')).collect();

    (!clean.is_empty() && !clean.starts_with('.') && clean.len() <= 200).then_some(clean)

}

/// Percent-encode a path segment.

fn seg(s: &str) -> String {

    s.bytes()

        .map(|b| if b.is_ascii_alphanumeric() || b"-._~".contains(&b) { (b as char).to_string() } else { format!("%{b:02X}") })

        .collect()

}

pub async fn upload(

    State(app): State<Shared>,

    headers: HeaderMap,

    Path((owner, name)): Path<(String, String)>,

    Query(q): Query<Named>,

    body: Bytes,

) -> Result<(StatusCode, Json<hub_api::Attachment>), ApiError> {

    let c = caller(&app, &headers).await?;

    let me = c.require("issues:write").or_else(|_| c.require("repo:write"))?.clone();

    let (_, row, _) = reach(&app, &c, &owner, &name, Access::Read).await?;

    let Some(file) = file_name(&q.name) else {

        return Err(ApiError(

            StatusCode::UNPROCESSABLE_ENTITY,

            "give the file a name (?name=FILE): plain, not hidden, at most 200 bytes".into(),

        ));

    };

    if body.is_empty() {

        return Err(ApiError(StatusCode::UNPROCESSABLE_ENTITY, "the file is empty".into()));

    }

    if body.len() > ATTACHMENT_MAX {

        return Err(ApiError(StatusCode::PAYLOAD_TOO_LARGE, format!("an attachment is at most {} MiB", ATTACHMENT_MAX >> 20)));

    }

    let image = image_type(&body);

    let content_type = image.unwrap_or("application/octet-stream");

    let hash = hex::encode(blake3::hash(&body).as_bytes());

    let path = crate::web::releases::blob_path(&app, &hash);

    if !path.exists() {

        let parent = path.parent().expect("a blob is in a directory");

        tokio::fs::create_dir_all(parent).await.map_err(|e| ApiError(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;

        let tmp = path.with_extension("partial");

        tokio::fs::write(&tmp, &body).await.map_err(|e| ApiError(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;

        tokio::fs::rename(&tmp, &path).await.map_err(|e| ApiError(StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;

    }

    let a = db::attachments::add(&app.db, row.id, &file, body.len() as i64, &hash, content_type, Some(me.id)).await?;

    let url = format!("{}/{}/{}/attachments/{}/{}", app.config.base_url().trim_end_matches('/'), row.owner, row.name, a.id, seg(&file));

    let markdown = if image.is_some() { format!("![{file}]({url})") } else { format!("[{file}]({url})") };

    Ok((

        StatusCode::CREATED,

        Json(hub_api::Attachment {

            id: a.id,

            name: file,

            size: a.size,

            content_type: content_type.into(),

            inline: image.is_some(),

            url,

            markdown,

        }),

    ))

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn only_real_images_show_in_place() {

        assert_eq!(image_type(b"\x89PNG\r\n\x1a\n...."), Some("image/png"));

        assert_eq!(image_type(&[0xFF, 0xD8, 0xFF, 0xE0]), Some("image/jpeg"));

        assert_eq!(image_type(b"GIF89a.."), Some("image/gif"));

        assert_eq!(image_type(b"RIFF\0\0\0\0WEBPVP8 "), Some("image/webp"));

        assert_eq!(image_type(b"<svg xmlns=\"http://www.w3.org/2000/svg\"><script/></svg>"), None, "an SVG is a download");

        assert_eq!(image_type(b"<html><script>alert(1)</script>"), None);

    }

    #[test]

    fn file_names_are_kept_plain() {

        assert_eq!(file_name("C:\\Users\\a\\shot.png").as_deref(), Some("shot.png"));

        assert_eq!(file_name("../../etc/passwd").as_deref(), Some("passwd"));

        assert_eq!(file_name("a\"b<c>.txt").as_deref(), Some("abc.txt"));

        assert_eq!(file_name(".env"), None);

        assert_eq!(file_name("  "), None);

    }

}

//! Attachments (oxygenhub#350): files people attach to issues, comments and

//! proposals, by content in the assets store.

use super::{now_ms, Pool};

#[derive(Clone, Debug, sqlx::FromRow)]

pub struct Attachment {

    pub id: i64,

    pub repo_id: i64,

    pub name: String,

    pub size: i64,

    pub hash: String,

    pub content_type: String,

    pub uploader_id: Option<i64>,

    pub created_ms: i64,

}

pub async fn add(

    pool: &Pool,

    repo_id: i64,

    name: &str,

    size: i64,

    hash: &str,

    content_type: &str,

    uploader_id: Option<i64>,

) -> sqlx::Result<Attachment> {

    sqlx::query_as(

        "INSERT INTO attachments (repo_id, name, size, hash, content_type, uploader_id, created_ms) VALUES ($1, $2, $3, $4, $5, $6, $7) RETURNING *",

    )

    .bind(repo_id)

    .bind(name)

    .bind(size)

    .bind(hash)

    .bind(content_type)

    .bind(uploader_id)

    .bind(now_ms())

    .fetch_one(pool)

    .await

}

/// One of a repository's attachments.

pub async fn get(pool: &Pool, repo_id: i64, id: i64) -> sqlx::Result<Option<Attachment>> {

    sqlx::query_as("SELECT * FROM attachments WHERE repo_id = $1 AND id = $2").bind(repo_id).bind(id).fetch_optional(pool).await

}

/// Whether any attachment keeps the blob `hash`.

pub async fn hash_in_use(pool: &Pool, hash: &str) -> sqlx::Result<bool> {

    let n: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM attachments WHERE hash = $1").bind(hash).fetch_one(pool).await?;

    Ok(n > 0)

}

## 0.9.19 (2026-11-01)

- **Added: attachments on issues and comments (#350).** Screenshots and any other file: `POST /api/v1/repos/OWNER/NAME/attachments?name=FILE` with the file's bytes answers with its address and the Markdown to use, and `oh issue create` and `oh issue comment` take `--attach FILE` (repeatable), so a screenshot pasted into Claude Code can go onto the issue it files. An image (by its bytes: PNG, JPEG, GIF, WebP) shows in place; anything else, SVG included, is a download. Attachments are served under the repository's read rules and can run nothing (no sniffing, a policy that allows nothing, never in a shared cache). Pasting and dragging into the web editors come later.

version = "0.9.19"

version = "0.9.19"

version = "0.9.19"

version = "0.9.19"

/// `POST /repos/{owner}/{name}/attachments?name=FILE` (oxygenhub#350): a

/// file attached for an issue, comment or proposal to show; the body is the

/// file's bytes.

#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]

pub struct Attachment {

    pub id: i64,

    pub name: String,

    pub size: i64,

    /// Checked from the bytes: an image the page may show, or

    /// `application/octet-stream`.

    pub content_type: String,

    /// An image shown in place; anything else is a download.

    pub inline: bool,

    pub url: String,

    /// What to put in an issue or comment: `![name](url)` for an image,

    /// `[name](url)` otherwise.

    pub markdown: String,

}

        ("Attachment", schemars::schema_for!(Attachment)),

mod attachments;

pub use attachments::image_type as attachment_image_type;

        .route(

            "/repos/{owner}/{name}/attachments",

            post(attachments::upload).layer(axum::extract::DefaultBodyLimit::max(attachments::ATTACHMENT_MAX + 4096)),

        )

pub mod attachments;

        .route("/{owner}/{name}/attachments/{id}/{file}", get(releases::attachment))

    // Attachments (#350) keep blobs in the same store.

    let attached = crate::db::attachments::hash_in_use(&app.db, hash).await.unwrap_or(true);

    if !attached && !rdb::hash_in_use(&app.db, hash).await.unwrap_or(true) {

/// `GET /{owner}/{name}/attachments/{id}/{file}` (#350): an attachment, to

/// whoever may read the repository. Only an image whose bytes say so shows

/// in place; anything else is a download. Nothing here can run in the

/// hub's origin: no sniffing, a policy that allows nothing, and never

/// cached by a shared cache (the repository may be private).

pub async fn attachment(

    State(app): State<Shared>,

    viewer: Viewer,

    Path((owner, name, id, file)): Path<(String, String, i64, String)>,

) -> Result<Response, Error> {

    let shell = Shell::new(&app, &format!("/{owner}/{name}"), &viewer);

    let (_, row, _) = lookup(&app, &shell, &viewer, &owner, &name).await?;

    let a = crate::db::attachments::get(&app.db, row.id, id).await.map_err(|e| Error::from_db(shell.clone(), e))?;

    let Some(a) = a.filter(|a| a.name == file) else { return Err(Error::not_found(shell)) };

    let bytes = tokio::fs::read(blob_path(&app, &a.hash)).await.map_err(|_| Error::not_found(shell.clone()))?;

    let inline = crate::api::attachment_image_type(&bytes).is_some();

    let disposition = format!("{}; filename=\"{}\"", if inline { "inline" } else { "attachment" }, a.name.replace('"', ""));

    let ct = if inline { a.content_type.clone() } else { "application/octet-stream".into() };

    Ok((

        [

            (header::CONTENT_TYPE, ct),

            (header::CONTENT_DISPOSITION, disposition),

            (header::X_CONTENT_TYPE_OPTIONS, "nosniff".to_string()),

            (header::CONTENT_SECURITY_POLICY, "default-src 'none'; sandbox".to_string()),

            (header::CACHE_CONTROL, "private, max-age=86400".to_string()),

        ],

        bytes,

    )

        .into_response())

}

/// oxygenhub#350: files attached to issues. Over the API, with the file's

/// bytes; an image (by its bytes) shows in place, anything else, an SVG

/// included, is a download; nothing served can run; a private repository's

/// attachments are its readers' only; uploading needs a token.

#[tokio::test(flavor = "multi_thread")]

async fn attachments_are_uploaded_and_served_safely() {

    let h = hub().await;

    db::accounts::create_account(&h.app.db, "andy", "[email protected]", "x", "salt", true).await.unwrap();

    create(&h.app, "andy", "demo").await;

    let send = |path: String, bytes: Vec<u8>, token: Option<&'static str>| {

        let app = h.app.clone();

        async move {

            let mut req = Request::builder().method("POST").uri(path).header(header::CONTENT_TYPE, "application/octet-stream");

            if let Some(t) = token {

                req = req.header(header::AUTHORIZATION, format!("Bearer {t}"));

            }

            let res = oxygenhub::router(app).oneshot(req.body(Body::from(bytes)).unwrap()).await.unwrap();

            let status = res.status();

            let body = res.into_body().collect().await.unwrap().to_bytes();

            (status, String::from_utf8_lossy(&body).into_owned())

        }

    };

    let get = |path: String| {

        let app = h.app.clone();

        async move {

            let res = oxygenhub::router(app).oneshot(Request::get(path).body(Body::empty()).unwrap()).await.unwrap();

            let hd = |k: header::HeaderName| res.headers().get(k).and_then(|v| v.to_str().ok()).unwrap_or("").to_string();

            let heads = (

                hd(header::CONTENT_TYPE),

                hd(header::CONTENT_DISPOSITION),

                hd(header::X_CONTENT_TYPE_OPTIONS),

                hd(header::CONTENT_SECURITY_POLICY),

                hd(header::CACHE_CONTROL),

            );

            let status = res.status();

            let body = res.into_body().collect().await.unwrap().to_bytes().to_vec();

            (status, heads, body)

        }

    };

    let png = b"\x89PNG\r\n\x1a\nnot really a picture".to_vec();

    let (st, _) = send("/api/v1/repos/andy/demo/attachments?name=shot.png".into(), png.clone(), None).await;

    assert_eq!(st, StatusCode::UNAUTHORIZED, "attaching needs a token");

    let (st, body) = send("/api/v1/repos/andy/demo/attachments?name=dir/shot.png".into(), png.clone(), Some("site")).await;

    assert_eq!(st, StatusCode::CREATED, "{body}");

    let a: hub_api::Attachment = serde_json::from_str(&body).unwrap();

    assert_eq!((a.name.as_str(), a.content_type.as_str(), a.inline), ("shot.png", "image/png", true));

    assert_eq!(a.markdown, format!("![shot.png]({})", a.url));

    let path = a.url.strip_prefix(&h.base).unwrap().to_string();

    assert_eq!(path, format!("/andy/demo/attachments/{}/shot.png", a.id));

    let (st, (ct, cd, nosniff, csp, cache), bytes) = get(path.clone()).await;

    assert_eq!(st, StatusCode::OK);

    assert_eq!((ct.as_str(), nosniff.as_str()), ("image/png", "nosniff"));

    assert!(cd.starts_with("inline"), "{cd}");

    assert!(csp.contains("default-src 'none'") && csp.contains("sandbox"), "{csp}");

    assert!(cache.starts_with("private"), "{cache}");

    assert_eq!(bytes, png);

    let (st, _, _) = get(format!("/andy/demo/attachments/{}/other.png", a.id)).await;

    assert_eq!(st, StatusCode::NOT_FOUND, "the name must match");

    // An SVG says it is an image; its bytes are a script's: a download.

    let svg = b"<svg xmlns=\"http://www.w3.org/2000/svg\"><script>alert(1)</script></svg>".to_vec();

    let (st, body) = send("/api/v1/repos/andy/demo/attachments?name=logo.svg".into(), svg, Some("site")).await;

    assert_eq!(st, StatusCode::CREATED, "{body}");

    let s: hub_api::Attachment = serde_json::from_str(&body).unwrap();

    assert!(!s.inline && s.content_type == "application/octet-stream" && s.markdown == format!("[logo.svg]({})", s.url));

    let (_, (ct, cd, _, _, _), _) = get(s.url.strip_prefix(&h.base).unwrap().to_string()).await;

    assert_eq!(ct, "application/octet-stream");

    assert!(cd.starts_with("attachment"), "{cd}");

    let (st, _) = send("/api/v1/repos/andy/demo/attachments?name=.env".into(), b"x".to_vec(), Some("site")).await;

    assert_eq!(st, StatusCode::UNPROCESSABLE_ENTITY, "a hidden file name is refused");

    // A private repository's attachments are for its readers.

    h.app.repos.create(&RepoName::parse("andy/secret").unwrap(), None).unwrap();

    db::repos::create(&h.app.db, "andy", "secret", "", hub_api::Visibility::Private).await.unwrap();

    let (st, body) = send("/api/v1/repos/andy/secret/attachments?name=s.png".into(), png.clone(), Some("site")).await;

    assert_eq!(st, StatusCode::CREATED, "{body}");

    let p: hub_api::Attachment = serde_json::from_str(&body).unwrap();

    let (st, _, _) = get(p.url.strip_prefix(&h.base).unwrap().to_string()).await;

    assert_eq!(st, StatusCode::NOT_FOUND, "not to someone signed out");

}

        /// Attach a file (repeatable): a screenshot shows in place, anything else is a download link (#350)

        #[arg(long, short = 'a', value_name = "FILE")]

        attach: Vec<std::path::PathBuf>,

        /// Attach a file (repeatable): a screenshot shows in place, anything else is a download link (#350)

        #[arg(long, short = 'a', value_name = "FILE")]

        attach: Vec<std::path::PathBuf>,

        IssueCmd::Create { title, body, body_file, label, project, column, attach } => {

            let body = with_attachments(c, &base, body_of(body, body_file)?, &attach)?;

            let new = NewIssue { title, body, labels: label, assignees: vec![], milestone: None };

        IssueCmd::Comment { number, body, body_file, attach } => {

            let body = with_attachments(c, &base, body_of(body, body_file)?, &attach)?;

                bail!("give the comment with --body, --body-file or --attach");

}

/// `body` with each file attached to the repository and linked under it:

/// an image shown in place, anything else a download (#350). Files are

/// uploaded first, so a failed upload leaves nothing half made.

fn with_attachments(c: &Client, base: &str, body: String, files: &[std::path::PathBuf]) -> Result<String> {

    if files.is_empty() {

        return Ok(body);

    }

    let mut links = Vec::new();

    for f in files {

        let bytes = std::fs::read(f).with_context(|| format!("reading {}", f.display()))?;

        let name = f.file_name().map(|n| n.to_string_lossy().into_owned()).unwrap_or_else(|| "file".into());

        let answer = c.upload(&format!("{base}/attachments?name={}", enc(&name)), &bytes)?;

        let a: hub_api::Attachment =

            serde_json::from_str(&answer).with_context(|| format!("attaching {}: unexpected answer", f.display()))?;

        links.push(a.markdown);

    }

    let links = links.join("\n\n");

    Ok(if body.trim().is_empty() { links } else { format!("{}\n\n{links}", body.trim_end()) })

    assert!(code != 0 && err.contains("--body, --body-file or --attach"), "{err}");

/// oxygenhub#350: `oh issue create --attach` and `oh issue comment

/// --attach` upload each file and link it in the text: a screenshot shows

/// in place, anything else is a download link.

#[tokio::test(flavor = "multi_thread")]

async fn oh_attaches_files_to_issues_and_comments() {

    let h = hub().await;

    db::accounts::create_account(&h.app.db, "andy", "[email protected]", "x", "salt", true).await.unwrap();

    h.app.repos.create(&RepoName::parse("andy/demo").unwrap(), None).unwrap();

    db::repos::create(&h.app.db, "andy", "demo", "A demo", hub_api::Visibility::Public).await.unwrap();

    let work = tempfile::tempdir().unwrap();

    let mut c = Repo::init(work.path()).unwrap();

    c.config.set("remote.origin.url", &format!("{}/andy/demo", h.base)).unwrap();

    c.config.set("remote.origin.token", "site").unwrap();

    c.save_config().unwrap();

    let w = work.path();

    std::fs::write(w.join("shot.png"), b"\x89PNG\r\n\x1a\nscreen").unwrap();

    std::fs::write(w.join("log.txt"), "boom\n").unwrap();

    let (code, out, err) =

        oh(w, &[], &["issue", "create", "-t", "It broke", "-b", "See:", "--attach", "shot.png", "--attach", "log.txt", "--json"]).await;

    assert_eq!(code, 0, "{err}");

    let issue: hub_api::Issue = serde_json::from_str(&out).unwrap();

    assert!(issue.body.starts_with("See:\n\n![shot.png]("), "{}", issue.body);

    assert!(issue.body.contains("[log.txt]("), "{}", issue.body);

    let (code, _, err) = oh(w, &[], &["issue", "comment", &issue.number.to_string(), "--attach", "shot.png"]).await;

    assert_eq!(code, 0, "{err}");

    let (code, _, err) = oh(w, &[], &["issue", "comment", &issue.number.to_string(), "--attach", "missing.png"]).await;

    assert_ne!(code, 0);

    assert!(err.contains("missing.png"), "{err}");

    let (_, out, _) = oh(w, &[], &["api", &format!("/repos/andy/demo/issues/{}/comments", issue.number)]).await;

    assert!(out.contains("![shot.png]("), "{out}");

}

| `oh issue create -t TITLE [-b BODY \| -F FILE] [-l LABEL]… [-p N [--column NAME]] [-a FILE]…` | Open an issue; `-p` also puts it on the owner's project N; `-a` attaches a file (a screenshot shows in place, anything else is a download link) |

| `oh issue comment N -b BODY [-a FILE]…` | Comment, with attached files as `issue create` takes them |

**Attachments** (oxygenhub#350). `POST /api/v1/repos/{owner}/{name}/attachments?name=FILE` with a file's bytes (at most 25 MiB; `issues:write` or `repo:write`, and read access) keeps it by content in the assets store and answers with its `url` and the Markdown to put in an issue, comment or proposal. Its type is read from its bytes: a PNG, JPEG, GIF or WebP is an image shown in place; anything else, an SVG included, is a download (`application/octet-stream`, `Content-Disposition: attachment`). `GET /{owner}/{name}/attachments/{id}/{file}` serves it to whoever may read the repository, with `nosniff`, `Content-Security-Policy: default-src 'none'; sandbox` and `Cache-Control: private`. A blob is removed only when neither a release asset nor an attachment keeps it.