Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
52 commits
Select commit Hold shift + click to select a range
07623c0
feat(app-store): manifest schema, validator, catalog builder and firs…
richiemcilroy Nov 14, 2026
9350e3e
feat(database): app store installations and events tables
richiemcilroy Nov 14, 2026
1c763ca
fix(app-store): export permission type from the manifest schema
richiemcilroy Nov 14, 2026
b1f7877
feat(web): app store API, installs, signed connections and event deli…
richiemcilroy Nov 14, 2026
fc559fc
feat(web): send app store events when Caps are ready, transcribed, su…
richiemcilroy Nov 14, 2026
2fecd47
feat(web): App Store pages, install flow, settings form and Cap menu …
richiemcilroy Nov 14, 2026
be49989
feat(desktop): App Store page, synced installs, app backgrounds, capt…
richiemcilroy Nov 14, 2026
53b575b
fix(desktop): use this gpui's async update and global APIs in the App…
richiemcilroy Nov 14, 2026
49b50bb
chore(desktop): drop unused App Store helpers
richiemcilroy Nov 14, 2026
392d8a8
test(desktop): count the Apps settings page
richiemcilroy Nov 14, 2026
245f39f
test(desktop): pair the App Store strings with their English literals…
richiemcilroy Nov 14, 2026
576ba0c
fix(app-store): keep the package entry browser safe; move building an…
richiemcilroy Nov 14, 2026
df5a174
improve(web): skip a README title that repeats the app name
richiemcilroy Nov 14, 2026
4209dd1
fix(app-store): write the manifest schema in the repo's Biome format
richiemcilroy Nov 14, 2026
fc232da
fix(web): load the App Store emitter lazily from upload, transcript a…
richiemcilroy Nov 14, 2026
86cf55c
refactor(web): drop server-only markers from App Store modules
richiemcilroy Nov 14, 2026
5b30a8f
fix(web): load Cap menu actions through the App Store API
richiemcilroy Nov 14, 2026
4041b37
test(web): mock the Apps nav icon
richiemcilroy Nov 14, 2026
a5d14a0
fix(web): only the Cap's owner can run app actions on it
richiemcilroy Nov 14, 2026
3559ada
fix(web): retry App Store events whose delivery could not be queued
richiemcilroy Nov 14, 2026
bb0f0b9
fix(web): announce cap.ready before transcription checks
richiemcilroy Nov 14, 2026
4c50121
fix(web): keep DNS checks and first-party handlers inside the action …
richiemcilroy Nov 14, 2026
5fe0eff
fix(web): keep saved secrets hidden when an app changes a field type
richiemcilroy Nov 14, 2026
b1d31b0
feat(app-store): refuse updates that turn a secret setting into plain…
richiemcilroy Nov 14, 2026
1e26b33
refactor(web): serve first-party connections through HttpApi
richiemcilroy Nov 14, 2026
43c7e92
fix(build): cache the generated App Store catalog and assets
richiemcilroy Nov 14, 2026
f8bf1bb
docs(app-store): color looks set the whole grade
richiemcilroy Nov 14, 2026
1e798aa
fix(desktop): scope app installs and Cap actions to the signed-in acc…
richiemcilroy Nov 14, 2026
2e7651c
chore(desktop): drop comments that restate App Store code
richiemcilroy Nov 14, 2026
104e734
fix(web): organization apps only hear about Caps shared with the orga…
richiemcilroy Nov 14, 2026
01a0bb7
fix(desktop): show Cap actions as soon as they load and retry failed …
richiemcilroy Nov 14, 2026
9d16d29
fix(web): stop exposing first-party connections on a public route
richiemcilroy Nov 14, 2026
4f105c0
Merge remote-tracking branch 'origin/main' into feat/app-store
richiemcilroy Nov 16, 2026
2fa98ef
fix(app-store): verify the signed kind and target app, document key r…
richiemcilroy Nov 16, 2026
3e42473
fix(app-store): decide first-party apps from an allowlist in code, no…
richiemcilroy Nov 16, 2026
43b7466
fix(app-store): treat a trailing-dot host like the bare host in conne…
richiemcilroy Nov 16, 2026
c4e3f89
fix(app-store): reject control, zero-width and bidi characters in lis…
richiemcilroy Nov 16, 2026
024c3f4
fix(web): rate limit App Store actions and installation changes per user
richiemcilroy Nov 16, 2026
8bf7dfd
Merge remote-tracking branch 'origin/main' into feat/app-store
richiemcilroy Nov 16, 2026
18c1595
chore(desktop): mark catalog helpers used only by tests
richiemcilroy Nov 16, 2026
0c91fee
fix(desktop): keep a fetched App Store catalog when the cache cannot …
richiemcilroy Nov 16, 2026
7af1614
fix(desktop): read a non-JSON app action response as a plain failure
richiemcilroy Nov 16, 2026
becd3f6
fix(desktop): truncate long app action notices and show the full text…
richiemcilroy Nov 16, 2026
e97b99e
fix(app-store): Aurora ships ten backgrounds, not eight
richiemcilroy Nov 16, 2026
81652aa
perf(web): start App Store event work after the response, not during it
richiemcilroy Nov 16, 2026
d4f6d0d
fix(web): keep the Apps page footer clear of the messenger button
richiemcilroy Nov 16, 2026
0e79c46
fix(web): prune App Store event markers older than 30 days in the dai…
richiemcilroy Nov 16, 2026
d086679
fix(web): tell repeated app actions apart and let a long app list scr…
richiemcilroy Nov 16, 2026
d573a34
test(web): avoid an unchecked index in the action label test
richiemcilroy Nov 16, 2026
b4d69c8
fix(desktop): show cached App Store icons at startup without waiting …
richiemcilroy Nov 16, 2026
b6fad58
fix(web): word the Discord missing-webhook error for a wrong URL too
richiemcilroy Nov 16, 2026
363fc9e
fix(desktop): outline App Store icons so dark icons stay visible on d…
richiemcilroy Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ jobs:
- 'Cargo.lock'
gpui:
- '.gitattributes'
- 'packages/app-store/test/fixtures/**'
- 'scripts/setup.js'
- 'apps/desktop-gpui/**'
- 'apps/media-server/src/__tests__/fixtures/**'
Expand Down Expand Up @@ -99,6 +100,12 @@ jobs:
run: |
node --test scripts/bun-scripts.test.mjs

- name: Validate App Store apps
run: |
git fetch --no-tags --depth=1 origin main
bun app-store validate --base FETCH_HEAD
bun run --cwd packages/app-store test

- name: Test Loops profile sync
run: |
bun test scripts/loops/profile.test.ts scripts/loops/lifecycle.test.ts
Expand Down
141 changes: 141 additions & 0 deletions app-store/ARCHITECTURE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
# App Store architecture

Check failure on line 1 in app-store/ARCHITECTURE.md

View workflow job for this annotation

GitHub Actions / Lint (Biome)

format

File content differs from formatting output

This is how Cap Apps work end to end: what an app is, where it lives, how it reaches people, and what keeps it safe and fast. If you want to build an app, start with [README.md](./README.md). This document is for people working on the store itself.

## Principles

1. **One app, one manifest, one store.** There is no separate web store and desktop store. An app lists what it contributes, and Cap works out where it runs from that. People install an app once and it works everywhere they use Cap.
2. **Apps declare, Cap draws.** No app ships UI code, on the web or on desktop. Apps describe settings fields, actions and content, and Cap renders all of it with its own components. Every app looks native, stays fast, and keeps working when Cap's design changes.
3. **Trust follows the code.** Content apps have no code at all. Connection apps run their code on their author's own server and only see what their declared permissions allow. Code that runs on the device (WebAssembly, in a later API version) gets its own sandbox and capability list.
4. **The repo is the registry.** Every app is a folder in `app-store/apps`. A pull request is a submission, CI is the first reviewer, and merging publishes. Cap's build turns the folder into a signed, content-addressed catalog.
5. **Guards are code, not prose.** Every rule in the guidelines that a machine can check is checked by `bun app-store validate`, in CI and again when the catalog is built.

## Where things live

```
app-store/
README.md Build an app (start here)
GUIDELINES.md Review rules
ARCHITECTURE.md This file
manifest.schema.json Generated from the manifest schema, for editor autocomplete
templates/ Starting points used by `bun app-store new`
apps/<id>/ One folder per app

packages/app-store/ @cap/app-store: manifest schema, validator, catalog builder,
CLI, request signing and verification
apps/web/ Store pages, install API, event delivery, actions
apps/desktop-gpui/ Store page in Settings, catalog sync, content and actions in the editor
```

## What an app can contribute (API version 1)

| Contribution | Kind | Runs | Where it shows up |
|---|---|---|---|
| `backgrounds` | Content | Desktop | Editor background picker, in an Apps tab |
| `captionStyles` | Content | Desktop | Editor caption presets |
| `colorLooks` | Content | Desktop | Editor color presets |
| `connection.events` | Connection | Author's server | Signed event delivery after Cap events |
| `connection.actions` | Connection | Author's server | Cap menus on web and desktop ("Send to Notion") |
| `connection.settings` | Connection | Cap | A settings form Cap renders at install, on web and desktop |

Where an app runs is worked out from its contributions and is never declared, so the badges in the store cannot drift from what the app does.

Planned for later API versions, with the manifest reserving room for them:

- **Transitions and effects** as WGSL shaders with a fixed uniform block, validated with naga in CI and on load.
- **Device code** as WebAssembly components (`wasm32-wasip2`), one frozen WIT world per API version, the way Zed does it. Device code will return the same declarative views connections use, so a slot never cares where its logic runs.
- **Scoped API tokens** for connections that need to call the Cap API, minted per install from the permissions the user granted.

## Manifest

Each app folder has a `manifest.json`. The schema lives in `packages/app-store/src/manifest.ts` and is the single source of truth: the validator, the catalog builder, the web app and the generated JSON Schema all come from it, and the desktop app parses every app in the repo in a test so its Rust types cannot drift.

```json
{
"$schema": "../../manifest.schema.json",
"apiVersion": 1,
"id": "discord",
"name": "Discord",
"version": "1.0.0",
"description": "Post new Caps to a Discord channel.",
"author": { "name": "Cap", "github": "CapSoftware" },
"license": "MIT",
"categories": ["communication"],
"connection": {
"url": "/api/app-store/first-party/discord",
"permissions": ["cap.transcript"],
"events": ["cap.ready"],
"settings": [
{ "key": "webhookUrl", "type": "secret", "label": "Webhook URL", "required": true }
],
"actions": [{ "id": "post", "title": "Post to Discord", "target": "cap" }]
}
}
```

`apiVersion` works like Shopify's dated API versions and Zed's frozen WIT folders. Each Cap client accepts a range of API versions, and the catalog tells it which apps it can run, so an older desktop build never sees an app it does not understand.

## Catalog

`bun app-store build` runs before the web app builds. It validates every app, then writes:

- `catalog.json`: every app's listing (name, description, icon, categories, derived platforms, permissions, contributions) plus the hash of each asset.
- `public/app-store/<id>/<sha256>.<ext>`: every asset under a content hash, served from Cap's CDN with an immutable cache header.

The web app reads the catalog in process. The desktop app fetches `GET /api/app-store/catalog` with an ETag, keeps the last copy on disk so the store works offline, downloads assets on install and checks each one against its hash before use.

The catalog also carries a `blocked` list. A blocked app disappears from the store, its connection receives nothing, and the desktop app stops loading its content on the next catalog sync. That is the kill switch.

## Installs

An install belongs to an account, never a device.

- **For me:** the app sees only Caps you own.
- **For my organization:** owners and admins install it, and it sees Caps their owners shared with that organization. A Cap that only belongs to the organization stays private to its owner. Owners can stop members from installing connection apps at all.

Installs live in `app_store_installations`, one row per app and scope, with settings encrypted using the same app-layer encryption as storage integrations. The row records the permissions and events that were granted. When a new version of an app asks for more, Cap keeps delivering only what was granted and asks for a review in the store, the way Slack asks for re-consent on new scopes.

Desktop content apps also work signed out. The desktop keeps a local install list, and when you sign in it merges that list with your account's installs.

## Connections

A connection is a server the app's author runs. Cap calls it, and it never calls into Cap's internals. All requests go to fixed paths under the declared `url`:

| Request | Path | When |
|---|---|---|
| Lifecycle | `POST {url}/lifecycle` | Installed, settings changed, uninstalled |
| Events | `POST {url}/events` | A subscribed Cap event happened |
| Actions | `POST {url}/actions/{actionId}` | Someone ran an action from a Cap menu |

Every request is signed with Ed25519, the way Discord signs interactions. Cap derives the signing key from its server secret, publishes the public key at `/.well-known/cap-app-store-keys.json`, and sends `Cap-Signature`, `Cap-Timestamp` and `Cap-Request-Id` headers. Apps verify with the public key, so no secret has to reach an author before the first request. `packages/app-store/src/signing.ts` has `verifyCapRequest`, which only needs Node's `crypto`, for authors to copy into a TypeScript server.

Payloads carry only what the install was granted. Every Cap event includes the basics (id, title, share link, owner name, creation time, duration). `cap.transcript` adds the transcript text, `cap.summary` adds the AI title, summary and chapters, and `cap.comments` adds comment text.

Delivery reuses the Infra webhook machinery: the same URL rules (https only, default port, public addresses only, no redirects), a 10 second timeout, retries with backoff over about a day on Vercel Workflow, and switching a connection off after sustained failures. Actions are synchronous with the same 10 second limit and return one of a fixed set of results (`toast` with a message, or `open` with an https URL) that Cap renders natively.

First-party connections declare a relative URL and use exactly the same signed requests, dispatched in process by the Cap server that sends them, so a self-hosted Cap serves its own and nothing listens publicly for them.

## Built-in apps

Slack, Amazon S3 and Google Drive already exist as integrations with their own flows. They appear in the store as built-in apps (`"builtin": "<name>"`), whose install button opens the existing setup. Only apps owned by Cap can declare `builtin`, and the validator enforces it.

## Guards

Checked by `bun app-store validate` in CI and again at catalog build:

- The manifest matches the schema exactly. Unknown keys are errors.
- `id` is kebab-case, 3 to 40 characters, matches the folder name, is unique, and does not contain "cap".
- `version` is semver and must go up whenever anything in the folder changes.
- Required files are present: `manifest.json`, `icon.png` (512x512, at most 256 KB), `README.md` and a license the guidelines accept.
- Only files the manifest references, plus the required ones, may be in the folder. No hidden files, symlinks, executables or archives.
- Images are PNG, JPEG or WebP, with dimensions and file sizes inside the limits for their slot, and the whole folder stays under 25 MB.
- Connection URLs are https on the default port, with a public hostname and no credentials, query or fragment.
- Settings keys are unique, select options are non-empty, there are at most 20 fields, and secrets are only ever `secret` fields.
- Only apps owned by Cap can be built-in.

Checked at runtime:

- Catalog assets are verified by hash before use.
- Connections only ever receive what was granted, within the 10 second limit, and are switched off after sustained failures.
- Action results are a fixed set; `open` URLs must be https.
- Strings from apps are rendered as plain text only, never as HTML or markdown, except the app's README on its store page, which is sanitised markdown.
35 changes: 35 additions & 0 deletions app-store/GUIDELINES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# App Store guidelines

`bun app-store validate` checks everything a machine can. A Cap maintainer checks the rest by hand before merging. These are the rules they use.

## Every app

- **One app, one job.** An app does one clear thing. Do not bundle unrelated content to look bigger, and do not publish near-copies of an existing app.
- **Honest listing.** The name, description, icon and README describe what the app really does. No keyword stuffing, no claims you cannot back up, no "best" or "#1".
- **Names.** Title Case nouns ("Aurora", "Notion Sync"), not sentences. Do not use "Cap" in the name or imply the app is made by Cap unless it is.
- **Icon.** Your own artwork, readable at 32 pixels, works on light and dark backgrounds. No default or placeholder icons.
- **README.** Starts with what the app does, then how to set it up. If it needs an account somewhere else, a paid plan, or sends data outside Cap, it says so.
- **You own what you ship.** Images, styles and names are yours or licensed for redistribution under the license you declare. No other companies' logos or trademarks unless you are that company or the app connects to their product.
- **Ownership.** The `author.github` account maintains the app. When someone else changes it, maintainers ask the author to review first, except for security fixes and broken builds.
- **Content.** Nothing hateful, sexual, violent, deceptive or illegal.

## Content apps

- Backgrounds look good behind a screen recording: no busy patterns that fight with text, no visible compression artefacts or banding, and no watermarks.
- Caption styles stay readable over light and dark video.
- Colour looks are subtle enough to use on real content. A look that only works on one clip is not a look.

## Connections

- **Ask for the least.** Request only the permissions and events the app uses. Reviewers check each one against the README.
- **No surprises.** Never post, publish or email anything on someone's behalf unless their settings or a click on your action asked for it.
- **Privacy policy.** Explain what you store, for how long, and how people delete it. Delete everything for an install when you receive `uninstalled`.
- **Verify every request** with Cap's public key and reject anything unsigned or stale.
- **Be fast.** Answer events within a few seconds and do slow work afterwards. Actions must answer within 10 seconds.
- **Secrets.** Collect API keys and tokens only through `secret` settings, never in a `text` field or by asking people to paste them anywhere else.
- **No tracking.** Do not use Cap data for advertising, profiling or training models, and do not add analytics that identify people.
- **Stay up.** Connections that fail for days are switched off. Apps that stay broken are removed from the store.

## Removal

Cap can remove an app, or block it remotely through `app-store/blocked.json`, if it breaks these guidelines, stops working, or puts people at risk. A blocked app disappears from the store, its connection stops receiving requests, and Cap Desktop stops loading its content.
Loading
Loading