Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
8 changes: 5 additions & 3 deletions docs/app-kit/api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,7 @@ resolves through:
|---|---|---|
| `fmtCurrency(value, currency = 'USD', options?)` | `@kirocrew/app-sdk` | Money in the host's locale. |
| `APP_SDK_LEVEL` | `@kirocrew/app-sdk` | The seam level, equal to the gateway's `ctx.sdk_level`. |
| `appWebOrigin(name)` | `@kirocrew/app-sdk` | The app's own site on the dashboard's port, `http://<name>.apps.localhost:<port>`, for a backend with `backend.webOrigin: true`; available when the dashboard uses http on `localhost`, `127.0.0.1` or `kirocrew.localhost`, and `null` on IPv6 or any other dashboard host. Level 8. |
| `Select` | `@kirocrew/app-sdk/ui` | A themed inline dropdown: `options`, `optionLabels?`, `value`, `onChange`, `clearLabel?`, `disabled?`, `aria-label?`, `title?`, `className?`. Native list on touch devices. |
| `guideCaution` | `@kirocrew/app-sdk/ui` | Spread onto a control that removes something (`<Btn {...guideCaution}>`), so a dashboard guide shows its caution line before a press there. |

Expand Down Expand Up @@ -1924,9 +1925,10 @@ and level 7 adds the manifest's `agentReadOnlyDirs` (see
`permissions.desktopCapabilities`, the dashboard's
[project picker](#project-picker) (`ProjectPicker`) and
[`ctx.webhook_source`](#webhook-source-ctxwebhook_source), and level 8 adds
directory entries in `credentialMasks` (`"state/"`) and the dashboard's
[host sessions](#host-sessions) (`useHostSessions`); each level
includes every level below it. Several seams share level 7, and two share level 8, so an app that needs one
directory entries in `credentialMasks` (`"state/"`), the dashboard's
[host sessions](#host-sessions) (`useHostSessions`), and the manifest's
`backend.webOrigin` with the dashboard's `appWebOrigin(name)`; each level
includes every level below it. Several seams share level 7, and three share level 8, so an app that needs one
feature-detects it, never the level alone. Read it
with `getattr(ctx, "sdk_level", 0)`. When it is lower than your app needs, call
`ctx.health.mark_degraded(...)` with the consequence and keep serving what you can.
Expand Down
1 change: 1 addition & 0 deletions docs/app-kit/manifest-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -1580,6 +1580,7 @@ popover says the app did not respond.
| `backend.routes` | string | | Base route path for the backend |
| `backend.type` | string | `""` | Backend runtime: `"python"`, `"asgi"`, `"node"`, `"exec"` (execute the entry point file as-is), or `""` (auto-detect from `entryPoint` — a `.sh` file or an extensionless executable with a non-Python shebang is treated as a shell launcher) |
| `backend.signedPrincipal` | boolean | `false` | Add a signed `X-KiroCrew-Principal` claim to every request the reverse proxy forwards to this backend. Only the JSON boolean `true` turns it on. The claim says whether the gateway authenticated an `owner-session`, an `app-token`, an `agent-tool` call, or `none`. |
| `backend.webOrigin` | boolean | `false` | Serve this backend on its own site, `http://<name>.apps.localhost:<dashboard port>`, so a page the app frames rides the dashboard's own connection. Only the JSON boolean `true` turns it on, and the name must be at most 63 characters. The gateway forwards no credential and signs nothing on that site; the app authenticates its own pages. Read the origin with `appWebOrigin(name)` from `@kirocrew/app-sdk` (level 8). |

> **Note:** the shell-launcher auto-detect reads the entry point's shebang
> line, so a compiled/binary launcher (e.g. an ELF executable) cannot be
Expand Down
1 change: 1 addition & 0 deletions docs/feature-map/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -368,6 +368,7 @@ Third-party and builtin apps that add their own pages, crons and MCP tools.
| Rail app menu | Details and Unpin for one installed app, from its sidebar row. Details carries the Library tile's update badge when the registry reports a newer version. When the registry list fails to load, the menu shows the failure with an Ask the agent item. Update, Sync, Disable, and Uninstall stay on the detail page and the Library | Right-click, or the context-menu key, on an app row in the sidebar's Apps list | `shell/nav/appRailMenu.tsx`, `shell/nav/navRail.tsx` | `src/kiro_crew/apps/routes_registry.py` | `GET /api/apps/registry` |
| App detail | One app's manifest, config, permissions, uninstall | `/apps/detail/:name` | `pages/AppDetailRoute.tsx` (the route element, keyed by app name so each app gets a fresh page), `pages/AppDetailPage.tsx`, `pages/AppDetailPageArt.tsx` (hero banner, screenshot gallery), `pages/AppDetailLinks.tsx` (the app's own `links` as buttons in the Details card, host shown), `pages/appDetailPageTypes.ts` (view model), `pages/appDetailPageLabels.ts` (origin and lifecycle words), `pages/AppDetailAdoptionNotice.tsx` (a former built-in's pending, blocked or staged move to its registry copy), `pages/appDetailPageLocalSwitch.ts` (a local-only refusal's "Trust the repository and update" step), `pages/AppDetailPageLocalOnlyNotice.tsx` (the refusal's error notice, which offers that step), `pages/AppDetailGrantBoxes.tsx` (the worker auto-approve and user-session reach permission boxes), `pages/appDetailPageStagedGrants.ts` (the declared grants an update widened that wait for the owner's approval) | `src/kiro_crew/apps/routes_listing.py`, `src/kiro_crew/apps/routes_uninstall.py`, `src/kiro_crew/apps/routes_art.py`, `src/kiro_crew/apps/store_links.py` (`links` validation) | `GET /api/apps/{name}`, `GET /api/apps/{name}/manifest`, `GET /api/apps/{name}/config` |
| Installed app page | An app's own UI, served by the app | `/apps/:name` | `pages/AppPage.tsx` | app-owned | `POST /api/apps/{name}/token`, `POST /api/apps/{name}/open` |
| App web origin | An app that sets `backend.webOrigin` gets its own site on the dashboard's port, which the gateway relays to the app's backend (HTTP and WebSocket), so a frame of the app's pages loads over the one connection that carries the dashboard | The app's own frame, at the address `appWebOrigin(name)` in `@kirocrew/app-sdk` gives it — no route of its own | `app-sdk/webOrigin.ts` | `src/kiro_crew/apps/app_web_origin.py` (`build_app_web_origin_middleware`, placed by `dashboard/server_runtime/middleware_chain.py`) | any path on `http://<app>.apps.localhost:<dashboard port>` |
| App agent tools | MCP tools a first-party app declares in its manifest `agentTools` block and serves from its own process: the agent sees each one in `kirocrew-core`, the call is checked against the declared schema, and the gateway hands it to the app's declared route. A built-in adopted onto its own repository keeps its shipped copy's tools; any other installed or registry app's block lists nothing. No page of its own | An agent's tool call in chat, while the declaring app is enabled | — | `handlers/app_agent_tools.py` (`api_app_agent_tool_call`), `src/kiro_crew/apps/app_agent_tools.py` (the first-party reader), `src/kiro_crew/mcp_tools/app_tools.py` (the listing and forwarder), `src/kiro_crew/apps/routes_proxy.py` (`handle_app_api_proxy`) | `POST /api/app-tools/call` (strict internal: mcp-core only; it reaches `POST /apps/{name}/api/{route}` or the app's registered route) |
| App migration | Move an app's data after a packaging change | `/apps/migrate/:name` | `pages/MigrationPage.tsx` | `src/kiro_crew/apps/routes_uninstall.py` | `DELETE /api/apps/{name}/migrate-cleanup` |
| Builtin app surfaces | Top-level routes builtin apps claim | `/<app>` via the `/:builtinApp/*` catch-all | `apps/builtinRegistry.ts` → per-app page | per-app `backend/routes.py` | `POST /api/apps/<app>/...` per app |
Expand Down
93 changes: 93 additions & 0 deletions docs/system-specs/modules/app-kit-platform.md
Original file line number Diff line number Diff line change
Expand Up @@ -5853,6 +5853,99 @@ Writers: `website/src/app-sdk/hostSessions.ts`, `website/src/app-sdk/index.ts`,
its check read), `website/public/vendor/kirocrew-app-sdk.mjs`,
`apps/builtins/agent_worlds/app.json`.

## 18k. An app web origin is the app's own site on the dashboard's port

An app whose UI frames its own backend's pages (a local reverse proxy in front of
a third-party site is the case this exists for) needs that frame to have a real
origin, with its own cookies and storage, kept apart from the dashboard. Framing
the backend's loopback port gives it one only when the browser runs on the
gateway's machine: a dashboard reached through one `ssh -L` forward resolves that
port on the browser's machine, so the frame goes blank.

**Opt-in.** `backend.webOrigin: true` (`apps/manifest_sections.py`, parsed like
`signedPrincipal`: only the JSON boolean turns it on). The app name becomes a DNS
label, so `validate()` refuses it on a name longer than 63 characters.

**Routing.** `apps/app_web_origin.py::app_web_origin_middleware` sits in the
dashboard chain directly inside the deny-audit boundary and outside the host
canonicalization and the `Host` barrier (§ the chain in
`dashboard/server_runtime/middleware_chain.py`). A `Host` under `.apps.localhost`
is decided there and reaches no dashboard layer:

- served only to a direct local request (`is_direct_local_request`, and not
`is_proxied_request`): a loopback peer with no forwarding header, not relayed.
An `ssh -L` forward is served; a tailnet, relayed or proxied peer gets 421. A
request that arrived on the Session Manager listener's port gets 421 too,
checked by listener (`SsmGate.owns`) because this router runs before that
listener's gate;
- only on a port the dashboard's own loopback origins in `allowed_origins` name
(the bound port and `KIROCREW_ALLOWED_LOOPBACK_PORTS`), else 421. A missing
`Host` port is the HTTP default, 80, and is served only when 80 is one of those
dashboard ports;
- only for `<name>` that is installed, enabled, opted in, gateway-managed and has a
tracked backend port, else 404 with a body that names nothing; a name under the
suffix that is not one DNS label is 404 too;
- relayed to `http://127.0.0.1:<backend port>` with path, query and body
unchanged, HTTP and WebSocket, streaming, with no total time bound (an idle
bound only), and with `Host` set to the canonical app name and explicit port.
A WebSocket message under 64 MiB is relayed in either direction
(`_MAX_WS_MESSAGE_BYTES`, above aiohttp's 4 MiB default because a live document
sync can send larger frames); a larger one closes the relay with 1009. aiohttp
checks the size once a frame is complete, so the cap bounds a message built
from many frames or a compressed one. When either side ends, both legs close
with the code that side reported: no status (an empty close frame, or 1005)
becomes 1000, a dropped connection (1006) becomes 1001, and a code outside
1000-4999 becomes 1002, because those codes are never sent.

Every decision is audited: one SEL `api_access` row per served request
(`outcome=granted`, `resources` the canonical app host and path) and per refusal
(`outcome=denied`, the refusal reason in `error`), both `source=app_web_origin`.

**Credentials.** Nothing the gateway trusts crosses: `Authorization`, the
internal-auth headers, relay identity headers and every `X-KiroCrew-*` header are
dropped, the dashboard's `mc_token*` / `mc_refresh_*` cookies are removed from
`Cookie`, and the request is not signed. A backend treats `X-KiroCrew-Proxy` as
proof that the API proxy (§24) forwarded a call; a page on the app origin may be
a third party's scripts, so signing there would hand them the backend's
gateway-only API. The app's own credential (for example a launch token traded
for a host-only cookie) is the only one on this origin.

**Response.** Hop-by-hop headers and `Clear-Site-Data` are dropped, every
`Set-Cookie` loses its `Domain` (host-only, so one app's cookie never reaches
another app's name), and each comma-separated CSP policy the backend sent loses
only its `frame-ancestors` directive. Every other directive and every non-empty
policy stays enforced. One more policy carries `frame-ancestors 'self'` plus the
dashboard's loopback origins (`frame_ancestors_value`). The dashboard's own
security headers are not applied.

**Dashboard side.** `APP_WEB_ORIGIN_CSP_SOURCE` (`http://*.apps.localhost:*`) is in the
dashboard's `frame-src` and `connect-src` always (the frame, and the no-cors
reachability probe an app runs on it). The CSRF allowlist does not gain it, so a
page on an app origin cannot post to a dashboard API: `check_origin` refuses its
Origin. `.apps.localhost` is two labels below `localhost`, apart from the
single-label Remote Crew pane names and from `kirocrew.localhost`.

**Discovery.** `appWebOrigin(name)` on `@kirocrew/app-sdk`
(`website/src/app-sdk/webOrigin.ts`), App Kit seam level 8, answers
`http://<name>.apps.localhost:<location.port>` when the dashboard is on
`localhost`, `127.0.0.1` or `kirocrew.localhost` over http, and `null` otherwise.
That includes an IPv6 dashboard: CSP `frame-ancestors` cannot express its
bracketed host source, so the app origin cannot be framed there. A published
HTTPS host and a Remote Crew pane also have no app origin. An app on an older
host finds no such export and keeps its own loopback frame.

Not covered: a dashboard reached over a published HTTPS host (it has no wildcard
name or certificate for app hosts), a Remote Crew pane whose forward port differs
from the remote gateway's, and Session Manager forwards. Each keeps what the app
did before.

Writers: `apps/app_web_origin.py`, `apps/manifest_sections.py`, `apps/manifest.py`,
`dashboard/server_runtime/middleware_chain.py`,
`dashboard/server_runtime/security_headers.py`, `website/src/app-sdk/webOrigin.ts`,
`website/src/app-sdk/index.ts`, `website/public/vendor/kirocrew-app-sdk.mjs`,
`website/src/app-sdk/sdkLevel.ts`, `apps/app_sdk_level.py`.
Tests: `test/test_app_web_origin.py`, `website/src/app-sdk/webOrigin.test.ts`.

## 19. Spec Builder's backend is composed by lifecycle owner

Spec Builder's backend carries more orchestration than a typical app: agent turns
Expand Down
1 change: 1 addition & 0 deletions docs/system-specs/modules/sel.md
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,7 @@ Two bounds, and the tighter wins:
| Refresh tokens | `refresh_token_use`, `refresh_token_logout`, `access_cookie_revoked` (`source=refresh_tokens`) | `dashboard/handlers/auth_refresh.py` |
| ACP transport | `tool_interrupted` per-turn cancellation audit (`source=acp`) | `acp/client_turn.py`, `acp/client_tool_events.py` |
| Browser sign-in from the vault | One `api_access` row per vault fill (`browser_ask_vault_fill`, `outcome` = the fill's outcome word, or `unusable` when the picked login no longer fits) and per save (`browser_ask_vault_save`, `ok` / `failed`), `source=browser`, `resources` = the ask's origin and the item NAME. Never a username, password or page text | `browser_harness/vault_fill.py` |
| App web origins | One `api_access` row per request the app web origin router decides: `granted` when it relays to the app's backend, `denied` when it refuses (`source=app_web_origin`, `caller=app_web_origin`, `operation=<method> app web origin`) | `apps/app_web_origin.py` |
| Installed apps | `api_access` rows an app writes about its own decisions via `ctx.audit` (`source=app`, `caller=app:<name>`, `operation=<name>.<verb>`). Attribution is minted from the app name the context was built with, so there is no `caller=` parameter to pass the wrong value into — cooperative, not unforgeable, since in-process hook code can construct another app's SDK or reach `sel()` directly; `record` swallows a write failure, because auditing must not break the operation it only describes; `outcome` is not narrowed to a vocabulary (rewriting it would record something other than what happened), and the SDK adds no scrubbing of its own — `log_api_access` puts `outcome` through `_redact_and_clip` for every caller, because this seam is what turns that slot from an in-tree constant into caller text and the fix belongs at the boundary all fillers cross | `apps/audit_sdk.py` |

## APIs
Expand Down
Loading
Loading