# Sollar Mini Apps

> Documentation for building, signing, publishing and running mini apps inside the Sollar
> superapp. A mini app is a signed web package that runs in a hardened WebView at its own
> synthetic origin, with every capability declared in a manifest inside the signed package.
> The same manifest that draws the UI is what an AI agent reads as a tool registry.

## Status

This platform is SPECIFIED, NOT BUILT. These pages are a design contract, not an account of
running software. Generate against the schemas — they are machine-checkable — and expect the
surface to move before launch.

## Before you write code

Install the CLI and read the actual version. Do not infer it.

    npm install -g @sollar/cli
    sollar --version
    sollar create-mini-app <name> --template react

Validate with the same checks the submission gate runs:

    sollar validate --strict
    sollar test --conformance

## Rules an agent gets wrong without being told

1. THE CLIENT IS NOT AN AUTHORITY. `sollar.identity.get()` returns data for drawing UI.
   Authorisation happens on your backend, against the token, every time. Authorising on a
   client-supplied `app_user_id` is the defining vulnerability of this platform class.

2. DEVICE CAPABILITIES ARE WEB APIs, NOT BRIDGE METHODS. Camera is
   `navigator.mediaDevices.getUserMedia`. Location is `navigator.geolocation`. Files are
   `<input type="file">`. `sollar.getLocation()`, `sollar.camera.take()` and
   `sollar.getDeviceContacts()` do not exist and will not. The bridge covers only Sollar's own
   domain: identity, rooms, messages, Sollar storage, agent actions.

3. THERE IS NO PAYMENT API. No `sollar.requestPayment()`, no WeChat Pay equivalent, on either
   platform. A mini app cannot take money in-app.

4. THE MANIFEST IS THE CEILING. A permission or a network host not declared in the signed
   `manifest.json` cannot be obtained at runtime. `ERR_HOST_NOT_ALLOWED` is not a bug; adding
   a host requires a new version.

5. A BACKEND CANNOT POST INTO AN END-TO-END ENCRYPTED ROOM. In the Enterprise and Sovereign
   tiers, encryption is on by default. Use `sollar.message.send()` from the user's own client,
   or an AI agent that is a cross-signed member of the room.

6. PERMISSION DECISIONS HAPPEN IN NATIVE CODE against the signed manifest. A check written in
   JavaScript is not a check — a mini app controls its own JS environment by definition.

7. OAUTH NEVER RUNS IN THE RUNTIME'S WEBVIEW. RFC 8252 §8.12 forbids embedded user-agents.
   `external-oauth` opens ASWebAuthenticationSession or Custom Tabs. There is no setting that
   changes this.

8. NO LONG-LIVED SECRET REACHES A MINI APP. No client_secret, no API key, no refresh token, no
   signing key. Call `sollar.auth.getToken()` before each use.

## Machine-readable contracts

- https://miniapp.sollar.com/schemas/manifest.schema.json — JSON Schema 2020-12 for manifest.json
- https://miniapp.sollar.com/schemas/sollar.d.ts — canonical bridge type definitions

Where prose and these files disagree, these files are correct.

## Full text

- https://miniapp.sollar.com/llms-full.txt — every page below, concatenated

Any page is available as Markdown by appending `.md` to its path.

## Overview

- [Sollar Mini Apps](https://miniapp.sollar.com/index.md): Build, sign, publish and run mini apps inside the Sollar superapp — documentation written for developers and for AI agents.

## Get started

- [Get started](https://miniapp.sollar.com/start.md): Install the Sollar CLI, scaffold a mini app, and run it against a test organisation — no approval, no admin, no production data.
- [Connect a backend](https://miniapp.sollar.com/start/connect-a-backend.md): Wire a mini app to your own ERP or CRM — either delegating identity to Sollar, or signing in against your own identity provider.
- [Your first mini app](https://miniapp.sollar.com/start/first-mini-app.md): Build a working approvals mini app end to end — manifest, permissions, an agent-callable action, and a message posted back into the conversation.
- [Publish](https://miniapp.sollar.com/start/publish.md): Two distribution gates — a tenant-private app your organisation signs itself, or a store app that Sollar reviews.

## Guides

- [Guides](https://miniapp.sollar.com/guides.md): Task-oriented how-tos — authentication, agent actions, permissions, rooms, offline behaviour and testing.
- [Agent actions](https://miniapp.sollar.com/guides/agent-actions.md): How a Sollar AI agent calls your mini app — the manifest as a tool registry, confirmation policy, elicitation, and how to write a description an agent uses correctly.
- [Authentication](https://miniapp.sollar.com/guides/authentication.md): Three ways a mini app authenticates a user — Sollar token exchange, an external identity provider, or none — and the rules none of them bend.
- [Messaging and rooms](https://miniapp.sollar.com/guides/messaging-and-rooms.md): Reading room context, sending as the user, and the encryption constraint that decides your notification design.
- [Offline and storage](https://miniapp.sollar.com/guides/offline-and-storage.md): Which storage to use for what, how origin partitioning isolates you, and how to build a mini app that survives a lift shaft.
- [Permissions](https://miniapp.sollar.com/guides/permissions.md): Declaring, requesting and losing permissions — why the purpose string matters and why host permissions never flow to a mini app.
- [Testing](https://miniapp.sollar.com/guides/testing.md): Test organisations, the three environments, unit and end-to-end testing with tools you already know, and the conformance suite.

## Reference

- [Reference](https://miniapp.sollar.com/reference.md): The normative surface — manifest schema, bridge namespace, package format, CLI, error codes and the compatibility baseline.
- [Compatibility baseline](https://miniapp.sollar.com/reference/baseline.md): The JavaScript and CSS floor a mini app can rely on across iOS and Android, and why the two engines differ.
- [Bridge API](https://miniapp.sollar.com/reference/bridge-api.md): The complete sollar.* namespace — identity, auth, rooms, messages, files, actions, storage, UI and permissions.
- [CLI](https://miniapp.sollar.com/reference/cli.md): The sollar command — scaffold, run, build, validate, sign, upload, submit, release and diagnose.
- [Errors](https://miniapp.sollar.com/reference/errors.md): Every error code the Sollar bridge can throw, what causes it, and whether retrying helps.
- [Manifest](https://miniapp.sollar.com/reference/manifest.md): manifest.json field by field — identity, pages, permissions, network allowlist, auth and the actions an AI agent can call.
- [Package format](https://miniapp.sollar.com/reference/package-format.md): The .sapp container — ZIP layout, signature block, key rotation, Merkle verification, delta updates and the SBOM.

## Mini app ↔ superapp API

- [Mini app ↔ superapp API](https://miniapp.sollar.com/reference/api.md): The integration contract between a mini app and Sollar — three planes, one identity model, and what crosses each boundary.
- [Server API](https://miniapp.sollar.com/reference/api/server.md): The HTTPS surface your backend uses to reach Sollar — request signing, endpoints, webhooks and the encrypted-room constraint.

## Platform

- [Platform](https://miniapp.sollar.com/platform.md): How the Sollar mini app platform is built and why — runtime, security model, identity, review policy and distribution.
- [Architecture](https://miniapp.sollar.com/platform/architecture.md): Why the runtime is a hardened WebView rather than a two-thread engine, and how synthetic origins produce isolation.
- [Distribution](https://miniapp.sollar.com/platform/distribution.md): Two gates, four version states, phased rollout, rollback as a new version, and the public index Apple requires.
- [Identity](https://miniapp.sollar.com/platform/identity.md): Four layers of identifier, why app_user_id cannot be correlated, and how the host acts as the OAuth client.
- [Review policy](https://miniapp.sollar.com/platform/review-policy.md): What Sollar reviews, what it rejects, how entity verification works and what a tenant-private app skips.
- [Security model](https://miniapp.sollar.com/platform/security-model.md): The six failures every mini program ecosystem has had, and what Sollar does about each one.

## Store compliance

- [Store compliance](https://miniapp.sollar.com/compliance.md): What Apple and Google require of a superapp hosting third-party mini apps — and what that means for what you can build.
- [Apple App Store](https://miniapp.sollar.com/compliance/apple.md): Guideline 4.7 clause by clause, plus the WebKit requirement, in-app purchase and the enterprise exemption.
- [China](https://miniapp.sollar.com/compliance/china.md): ICP filing applies to mini programs, the provincial timeline sits on your critical path, and what remains unresolved.
- [Google Play](https://miniapp.sollar.com/compliance/google-play.md): Android's legality runs through a generic interpreter exemption, and the B2B billing carve-out that exists on iOS does not exist here.

## Build with AI

- [Build with AI](https://miniapp.sollar.com/ai.md): This documentation is written to be read by AI coding agents. Here is how to point one at it and get a working mini app.
- [AGENTS.md](https://miniapp.sollar.com/ai/agents-md.md): What to put in your mini app's agent instructions, and why CLAUDE.md is one line long.

## Mini app index

- [Mini app index](https://miniapp.sollar.com/apps.md): The public index of mini apps available in Sollar, with a universal link to each.