Osy#betaRun it on Osyrin: osyrin.com

Reference / UI

The artifacts kit — things made for review, every version kept, shown in a sandboxed viewer

PublishArtifact(subjectType, subjectId, name, contentType, bytes, delegation:) · ArtifactVersions(artifact) · ArtifactView(version, h:) · ArtifactFrame(version:, title:) · CommentOnArtifact(artifact, version, text, x:, y:)

`Osysharp.Artifacts` keeps what somebody — often an agent — made for review on a row of your app: an HTML prototype, a picture, a PDF, a markdown note. Publishing under the same name again makes a new version and keeps every old one. People comment on one version, at a point of it if they like. The viewer shows a version in a frame the browser sandboxes twice, so an agent-made page runs its script in an origin of its own and can never act as your app.

preview1 example compiled by CIuikitstoragesecurity

Source on GitHub: Osysharp.Artifacts — github.com/osysharp/artifacts ↗

Summary#

An app where work is reviewed — a design, a report, a page an agent drafted — needs three things for what is reviewed: it must be kept with every version, people must comment on a particular version, and it must be shown safely, because a page somebody else wrote (an agent above all) must never run as your app inside the reviewer's session.

app Studio {
  use Osysharp.Artifacts@0;
  use Osysharp.Storage;
  use Osysharp.Ui;
  model "model/**/*.osy";
}

Signature#

using Osysharp.Artifacts;

// The app answers who — nobody, until it does.
policy ReadsArtifactsOf(string subjectType, Guid subjectId) => …;     // sees a subject's artifacts and comments
policy WritesArtifactsOf(string subjectType, Guid subjectId) => …;    // publishes on it
policy CommentsOnArtifactsOf(string subjectType, Guid subjectId) => …; // comments (readers, until the app says)

Artifact          PublishArtifact(string subjectType, Guid subjectId, string name, string contentType, byte[] bytes,
                                  Guid? delegation = null);   // new, or a new version under the same name
List<FileVersion> ArtifactVersions(Artifact artifact);        // every version, the first first
ArtifactComment   CommentOnArtifact(Artifact artifact, int version, string text, decimal? x = null, decimal? y = null);
void              ResolveArtifactComment(ArtifactComment comment, bool resolved = true);

ArtifactView(FileVersion version, int h = 640)                // one version, in the sandboxed frame
ArtifactFrame(version: Guid, title: string, <style props>)   // the atom ArtifactView draws

Description#

An artifact and its versions#

An Artifact is on one row of the app — its subject, named by its type and id ("Design", design.Id) — and holds one FileAsset. Publishing under a name the subject already has calls File.Supersede on that file: the artifact is the same row, the new content is the current version, and every earlier version stays, listed by ArtifactVersions and viewable by ArtifactView (A file's history — supersede, and what each version keeps). A new version keeps the artifact's type; publish another type under a name of its own.

var page = PublishArtifact("Design", design.Id, "index.html", "text/html", bytes, delegation: work.Id);
foreach (var v in ArtifactVersions(page)) {
  Text("version " + v.Version);
  ArtifactView(v, h: 480);
}

What may be published#

text/html, image/png, image/jpeg, image/webp, image/gif, image/svg+xml, application/pdf, text/markdown, text/plain and application/json. The bytes are checked against the type: a "picture" that is really a page is refused, and so is text that is not UTF-8. A version is at most 25 MB. An HTML prototype must be one self-contained page; output of several files is several artifacts.

The organisation's policy#

ArtifactsSetup holds two settings an organisation's policy governs for every app it runs: MaxBytes (a Range: it may lower the 25 MB cap) and AllowPrototypes (a Lock: it may forbid HTML prototypes outright). PublishArtifact reads them on every upload, so the organisation's word holds whatever the app sets.

Why the viewer is safe#

Artifact bytes are served only by the platform's route /_artifacts/{version}/{name}, and every answer carries the CSP sandbox directive. The browser then gives the document an opaque origin, even when the address is opened directly in a tab: its script cannot read your app's cookies or storage, connect-src 'none' stops it calling your app or anywhere else, and it may not submit forms, open windows or navigate. Only HTML may run script at all; a picture, a PDF or a note is sandboxed with none. ArtifactFrame sets sandbox="allow-scripts" on the frame as well, so the sandbox is set twice, and it takes no address and no sandbox setting from your code.

A frame's request carries no sign-in, so the viewer's address is signed for the reader: the platform reads the artifact as them (ReadsArtifactsOf) and only then mints a short-lived address naming that one version. Somebody who may not see it gets an empty frame, and the address without its signature answers nothing.

⚠ Chromium will not show a PDF inside a sandboxed frame. Show a PDF artifact with the PDF viewer kit, or offer it as a download, rather than in ArtifactView.

Comments#

A comment is on one version — it stays with the version it was written on when a new one is published — and may name a point of the frame (x, y, each a fraction from 0 to 1). It is live: a page listing a version's comments shows a new one as it is written. ResolveArtifactComment marks it done.

Examples#

A design's prototypes, each shown sandboxed#

app Studio {
  use Osysharp.Artifacts@0;
  use Osysharp.Storage;
  use Osysharp.Ui;
  model "model/**/*.osy";
}

using Osysharp.Ui;
using Osysharp.Artifacts;

entity Design {
  [Required, MaxLength(80)] string Title;
  security { allow read when IsAuthenticated; }
}

// Whoever may read a design sees its artifacts and publishes on it.
policy ReadsArtifactsOf(string subjectType, Guid subjectId) => subjectType == "Design" && Design.Any(d => d.Id == subjectId);
policy WritesArtifactsOf(string subjectType, Guid subjectId) => ReadsArtifactsOf(subjectType, subjectId);

[Route("/designs/{id}/artifacts")]
component DesignArtifacts(Guid id) {
  render {
    Stack(gap: 2) {
      foreach (var a in Artifact.Where(x => x.SubjectType == "Design" && x.SubjectId == id).Include(x => x.File.CurrentVersion).ToList()) {
        Text(a.Name);
        ArtifactView(a.File.CurrentVersion, h: 720);
      }
    }
  }
}

Traps that cost real time#

The subject is two values, not a reference. An artifact can be on any row of any type, so it names it by type and id. Your policies decide what each pair means; a pair no policy admits is nobody's.

Frame(html) is not this. Frame shows a document with no script at all (Frame), which is what a mail preview wants. A prototype needs its script, which is why it has a viewer of its own.

See also#

Related

A file's history — supersede, and what each version keeps

Replacing a stored file's content while keeping what it said before. The FILE is the identity — a record pointing at it…

Frame

`Frame(html)` shows a whole HTML document inside the page, in a frame of its own — what a mail preview is. The document…