@ziprack/sdk 0.1.2 → 0.2.0

package/dist/docs/auth.md

@@ -0,0 +1,106 @@
+# Authentication — `auth@1`
+
+- [Introduction](#introduction)
+- [Declaring Attributes](#declaring-attributes)
+- [Reading the Participant](#reading-the-participant)
+- [Degrading Gracefully](#degrading-gracefully)
+- [Rack Side](#rack-side)
+
+<a name="introduction"></a>
+## Introduction
+
+`auth@1` answers one question for the applet — *who is this, and what am I allowed to know about
+them* — and one question for the deployment: *what can applets see about our people?* The second is
+the question a client's procurement team will ask, and this capability is where it has a single
+answer.
+
+Profile attributes are **Rack-owned and applet-requested**. Never applet-written. There is no
+`Rack.auth.set()`, and there never will be within `auth@1`.
+
+This capability has no runtime messages at all: the released profile travels in the launch payload.
+
+<a name="declaring-attributes"></a>
+## Declaring Attributes
+
+```json
+"requires": {
+    "capabilities": ["auth@1"],
+    "profile": ["display_name", "business_unit", "locale"]
+}
+```
+
+Keys match `^[a-z][a-z0-9_]*$`. Requesting an attribute is not obtaining it: the deployment's
+`ziprack-auth.php` lists what may ever be released, and anything outside that list is withheld
+silently.
+
+```php
+// config/ziprack-auth.php
+'releasable' => ['display_name', 'email', 'locale'],   // ZIPRACK_AUTH_RELEASABLE
+
+'claim_map' => [
+    'display_name' => 'name',
+    'email' => 'email',
+],
+```
+
+`display_name` is always released. Values stored through a roster import or `ziprack:profile:set`
+override the claim map, which is how attributes that do not exist on the user model — cohort,
+business unit, region — reach an applet.
+
+<a name="reading-the-participant"></a>
+## Reading the Participant
+
+```ts
+const launch = await Rack.init({ slug: 'my-applet' });
+
+launch.actor;                 // { id, name } — always present, no capability needed
+Rack.auth.user();             // { id, display_name, …released attributes } | null
+
+Rack.auth.attribute('business_unit');              // unknown → null
+Rack.auth.attribute('locale', 'en');               // unknown → 'en'
+Rack.auth.attribute<string[]>('regions', []);      // typed
+```
+
+Both are synchronous reads of launch data, so they are free to call in a render path.
+
+`actor` is the participant the Rack resolved: a logged-in user, or a cookie-keyed guest when the
+deployment enables guests. `Rack.auth.user()` is the *profile*, and exists only when `auth@1` is
+declared.
+
+<a name="degrading-gracefully"></a>
+## Degrading Gracefully
+
+An attribute you requested may be absent because the deployment does not release it, because nobody
+imported it, or because this participant is a guest. All three look the same to you, and all three
+must work.
+
+```ts
+const unit = Rack.auth.attribute<string>('business_unit');
+
+const intro = unit
+    ? `Here is what the ${unit} team said last quarter.`
+    : `Here is what your colleagues said last quarter.`;
+```
+
+Design the withheld path first and treat personalisation as an enhancement. An applet that renders
+`Hello, undefined` when an attribute is missing has failed validation of a kind the Rack cannot
+perform for you.
+
+<a name="rack-side"></a>
+## Rack Side
+
+```sh
+php artisan ziprack:profile:set ada@example.com business_unit "R&D"
+php artisan ziprack:roster:import people.csv      # email column + one column per attribute
+```
+
+Admin endpoints:
+
+| Route | Purpose |
+|---|---|
+| `GET /ziprack/admin/participants/{participant}/profile` | Current attributes and their sources. |
+| `PUT /ziprack/admin/participants/{participant}/profile` | Set attributes for one person. |
+
+To source attributes from SSO claims instead, bind
+`ZipRack\Auth\Contracts\ProfileAttributeSource`; `ClaimMapSource` is the default implementation and
+a reasonable starting point.

package/dist/docs/broadcast.md

@@ -0,0 +1,226 @@
+# Broadcast — `broadcast@1`
+
+- [Introduction](#introduction)
+- [Rooms](#rooms)
+- [Declaring Channels and Facilitator Events](#declaring-channels-and-facilitator-events)
+- [Joining and Publishing](#joining-and-publishing)
+- [Inviting People In](#inviting-people-in)
+- [Presence](#presence)
+- [Shared State](#shared-state)
+- [The Facilitator Role](#the-facilitator-role)
+- [Developing Against Rooms](#developing-against-rooms)
+
+<a name="introduction"></a>
+## Introduction
+
+`broadcast@1` is what makes group work repeatable: a climb with base camps, teams on separate
+boards, a live trivia round, a facilitated card game. It gives an applet rooms, presence, published
+events, a facilitator role and a shared key/value state.
+
+**The Rack holds the WebSocket, not the applet.** You publish and subscribe over `postMessage`; the
+Rack owns the socket and its authentication. An applet can never obtain or leak a channel token,
+and the trust model is identical to every other capability.
+
+Transport is Laravel Reverb. That is a deployment concern: nothing in the applet API mentions it.
+
+<a name="rooms"></a>
+## Rooms
+
+A **room** is an applet version plus its members. Every member has exactly one of two roles —
+`participant` or `facilitator` — and membership is orthogonal to attempts: a room may contain
+attempts (each person running their own inside a shared session) or none at all.
+
+Rooms are created by an admin, or from the console:
+
+```sh
+php artisan ziprack:room:create team-summit --name="Boston cohort" --mode=first_in
+# → join code: 7FQK2M   →  https://rack.example.com/r/7FQK2M
+```
+
+Participants arrive by code or QR, which is how CN already runs events.
+
+| Mode | Facilitator assignment |
+|---|---|
+| `opt_in` | Anyone in the room may claim the role. |
+| `first_in` | Granted automatically to the first joiner. |
+| `roster` | A preset list of people, resolved through `auth@1`. |
+
+Only `roster` depends on `auth@1`, so light group activities can run without an identity source at
+all — see [guests](installation.md#participants-and-guests).
+
+The room arrives in launch data:
+
+```ts
+Rack.broadcast.room;            // { id, code, name, status, mode } | null
+Rack.broadcast.role;            // 'participant' | 'facilitator' | null
+Rack.broadcast.isFacilitator;
+Rack.broadcast.members();       // RoomMember[]
+```
+
+`room` is `null` when the applet was launched outside a room. Handle it: the same applet is often
+launched both ways.
+
+<a name="declaring-channels-and-facilitator-events"></a>
+## Declaring Channels and Facilitator Events
+
+```json
+"broadcast": {
+    "channels": ["main", "board"],
+    "facilitator_events": ["advance", "lock", "reveal"]
+}
+```
+
+Channels default to `["main"]` if you declare none, cap at 20, and are namespaced to the room — an
+applet cannot address another room's channel. `$room` is reserved for the Rack.
+
+**`facilitator_events` is enforcement, not documentation.** An event named there is refused with
+`forbidden` unless the sender currently holds the facilitator role. Facilitator control is therefore
+not a separate capability: advancing, locking and revealing are ordinary events the Rack polices,
+and the applet decides what they mean.
+
+<a name="joining-and-publishing"></a>
+## Joining and Publishing
+
+```ts
+const main = await Rack.broadcast.join('main');
+
+const stop = main.listen<{ step: number }>('advance', (payload, from) => {
+    goToStep(payload.step);                       // from.participant_id, from.role
+});
+
+main.listen('*', ({ event, payload }) => log(event, payload));
+
+if (Rack.broadcast.isFacilitator) {
+    await main.publish('advance', { step: 3 });
+}
+
+stop();                 // unsubscribe one listener
+await main.leave();     // leave the channel
+```
+
+Payloads cap at 16 KB (`ziprack-broadcast.max_event_bytes`). Every published event is persisted, so
+the admin can replay a session's facilitator timeline afterwards.
+
+Events are delivered to everyone in the room, including the sender. Design handlers to be idempotent
+and to tolerate arriving out of order relative to your own optimistic updates.
+
+<a name="inviting-people-in"></a>
+## Inviting People In
+
+An applet on a projector often *is* the way people get into the room. Ask the Rack where to
+point them:
+
+```ts
+const { ok, data } = await Rack.broadcast.invite();
+// data → { code: '7FQK2M', url: 'https://rack.example.com/r/7FQK2M' }
+```
+
+The Rack holds the URL because a sandboxed applet cannot see the Rack's host, and the join
+prefix is a deployment setting (`ZIPRACK_ROOM_PREFIX`). What you do with it is yours: print the
+code on a slide, render the URL as a QR with whatever library you already bundle, or both.
+
+```ts
+if (ok) {
+    board.append(qr(data.url));       // your encoder, your styling
+    code.textContent = data.code;
+}
+```
+
+There is no facilitator gate. The room code is already in every member's launch payload and can
+be read aloud in two seconds, so refusing the URL would protect nothing and would break the rule
+that an applet stays usable while nobody holds the role.
+
+The call is **refused with `conflict` once the room is locked or closed**, because `/r/{code}`
+turns those scanners away. Handle it — that is the signal to take a stale QR off the screen:
+
+```ts
+Rack.broadcast.on('status', async ({ status }) => {
+    board.hidden = status !== 'open';
+});
+```
+
+Non-members get `forbidden`, as they do for `presence`. In mock mode the invite is the dev
+server page itself, so scanning it opens the second tab that forms the room.
+
+<a name="presence"></a>
+## Presence
+
+```ts
+const { data } = await Rack.broadcast.presence();
+data.members;   // [{ id, name, role, present }]
+
+Rack.broadcast.on('presence', ({ members }) => renderRoster(members));
+```
+
+A member counts as present when seen within 45 s (`ziprack-broadcast.presence_window_seconds`); the
+shell heartbeats for you. Treat presence as approximate — it is a roster, not a lock.
+
+Room-level events you can subscribe to:
+
+| Event | Payload |
+|---|---|
+| `presence` | `{ members }` |
+| `state` | `{ key, value, version }` |
+| `role` | `{ role, participant_id }` |
+| `status` | `{ status }` — `open`, `locked`, `closed` |
+
+<a name="shared-state"></a>
+## Shared State
+
+Server-authoritative, last write wins **per key**, with the Rack stamping a version.
+
+```ts
+await Rack.broadcast.state.set('phase', 'voting');
+
+const { data } = await Rack.broadcast.state.get(['phase', 'timer']);
+Rack.broadcast.state.snapshot();       // launch snapshot + everything pushed since, synchronously
+
+Rack.broadcast.on('state', ({ key, value, version }) => apply(key, value));
+```
+
+Up to 200 keys, 16 KB per value. Use it for the small facts everyone must agree on — the current
+phase, which card is face up, whether submissions are open — and use [`db@1`](database.md) room
+collections for the content itself.
+
+This is deliberately not a CRDT. If two people write the same key at the same moment, one of them
+wins and everyone converges on that value. Design keys so that matters as little as possible:
+one writer per key is the intended shape, and a facilitator-only key is the easiest way to get it.
+
+<a name="the-facilitator-role"></a>
+## The Facilitator Role
+
+```ts
+await Rack.broadcast.claim();                 // opt_in rooms
+await Rack.broadcast.transfer(participantId); // hand it on
+
+Rack.broadcast.on('role', ({ role, participant_id }) => {
+    if (participant_id === launch.actor.id) renderFacilitatorControls(role === 'facilitator');
+});
+```
+
+**The grant must survive a dropped connection.** A facilitator unseen for 60 s
+(`ziprack-broadcast.facilitator_grace_seconds`) is vacated by `ziprack:rooms:tick`, and in a
+`first_in` room the role is reassigned automatically. Schedule that command every minute, or a
+closed laptop strands a room.
+
+Build the participant view first and layer facilitator controls on top of it. Every applet using
+rooms must be usable in the window where nobody holds the role.
+
+<a name="developing-against-rooms"></a>
+## Developing Against Rooms
+
+Mock mode implements rooms over `BroadcastChannel`, so **two tabs of your dev server form a room**.
+Presence, published events, shared state and role transfer all work between them; the first tab to
+open takes the facilitator role by default.
+
+```json
+"broadcast": { "channels": ["main"], "facilitator_events": ["advance"], "mock_mode": "opt_in" }
+```
+
+`mock_mode` is read only by the mock and lets you rehearse `opt_in` claiming locally. For automated
+tests, drive the other side explicitly:
+
+```ts
+host.push({ event: 'advance', payload: { step: 2 }, channel: 'main',
+            from: { participant_id: 99, role: 'facilitator' } });
+```

package/dist/docs/conformance.md

@@ -0,0 +1,102 @@
+# Conformance
+
+- [Why It Exists](#why-it-exists)
+- [Running the Suite](#running-the-suite)
+- [What It Checks](#what-it-checks)
+- [In CI](#in-ci)
+- [Fleet Visibility](#fleet-visibility)
+
+<a name="why-it-exists"></a>
+## Why It Exists
+
+zipRACK's central promise is that an applet built against one Rack runs on another. Without
+something that verifies it, "standalone Racks united by a common format" is an aspiration.
+
+`ziprack/conformance` is a dev dependency every Rack installs and runs in CI. It asserts the
+deployment still honours `ziprack/1` — including a Rack someone has customised, which is exactly the
+case where you want proof rather than good intentions.
+
+<a name="running-the-suite"></a>
+## Running the Suite
+
+```sh
+php artisan ziprack:conformance
+php artisan ziprack:conformance --json
+```
+
+The suite runs inside a transaction that is rolled back, so it is safe against a live database. Each
+check builds its own fixture — a temporary applet, a version, a package — and cleans up after itself.
+
+```
+✓ manifest requires schema
+✓ installer rejects unsafe zips
+✓ unimplemented capability is refused
+✓ undeclared capability is refused
+✓ csp is tightened
+✓ retired version is gone
+✓ promotion requires review
+✓ completed attempt is frozen
+✓ attempts are pinned
+✓ statements are append-only
+✓ records are scoped and validated
+```
+
+<a name="what-it-checks"></a>
+## What It Checks
+
+Core checks run on every Rack:
+
+| Check | Asserts |
+|---|---|
+| `ManifestRequiresSchema` | A manifest missing or misstating `schema` fails validation with the expected error. |
+| `InstallerRejectsUnsafeZips` | A zip containing `..`, an absolute path or a symlink is refused. |
+| `UnimplementedCapabilityIsRefused` | An applet requesting a capability this Rack lacks is refused at install. |
+| `UndeclaredCapabilityIsRefused` | A runtime call the manifest did not declare acks `undeclared_capability`. |
+| `CspIsTightened` | The response CSP contains the required directives, and `img-src` does not contain `https:`. |
+| `RetiredVersionIsGone` | A retired version can no longer be launched. |
+| `PromotionRequiresReview` | A version adding a capability cannot be promoted unapproved. |
+
+Each installed capability contributes its own, so the suite grows with the Rack:
+
+| Check | Capability |
+|---|---|
+| `CompletedAttemptIsFrozen`, `AttemptsArePinned` | `attempt` |
+| `StatementsAreAppendOnly` | `activity` |
+| `RecordsAreScopedAndValidated` | `db` |
+| `UploadsAreScopedAndTyped` | `storage` |
+| `AiBudgetsAreEnforced` | `ai` |
+| `FacilitatorEventsAreEnforced` | `broadcast` |
+
+<a name="in-ci"></a>
+## In CI
+
+Publish a test that runs the suite inside the deployment's own Pest or PHPUnit run:
+
+```sh
+php artisan ziprack:conformance:install
+```
+
+which writes `tests/Feature/ZipRackConformanceTest.php`. From then on the deployment's normal test
+command is also its conformance gate, and a customisation that breaks the contract fails the build
+rather than a client's security review.
+
+<a name="fleet-visibility"></a>
+## Fleet Visibility
+
+```sh
+php artisan ziprack:status
+php artisan ziprack:status --json
+```
+
+```http
+GET /ziprack/health        # Authorization: Bearer {ZIPRACK_HEALTH_TOKEN}
+```
+
+Both report the format string, the core version, every installed capability package with the
+capability versions it implements, and any warnings a capability raises — for example
+`storage@1` running the null scanner, or a CSP host configuration that would reopen an exfiltration
+channel.
+
+The question this answers is **"which deployments still need the fix?"** without SSH-ing into eight
+machines. That question gets asked during a client security review, usually with a deadline
+attached.

package/dist/docs/database.md

@@ -0,0 +1,176 @@
+# Database — `db@1`
+
+- [Introduction](#introduction)
+- [Declaring Collections](#declaring-collections)
+- [Scopes](#scopes)
+- [Reading and Writing](#reading-and-writing)
+- [Queries](#queries)
+- [Permissions](#permissions)
+- [Quotas](#quotas)
+- [How It Is Stored](#how-it-is-stored)
+
+<a name="introduction"></a>
+## Introduction
+
+`db@1` gives an applet CRUD over records in collections it declared, at a scope it declared. This is
+working state: ideas on a board, a team roster, a saved layout, a shared catalog.
+
+Records are mutable and arbitrarily shaped, which is exactly why **a JSON Schema is required, not
+optional**. The schema is what the Rack validates writes against, what the admin renders and exports
+records from, and what the installer derives indexes from. Without it, `db@1` would trade the
+uniform export that makes [statements](activity.md) valuable for a pile of untyped JSON.
+
+<a name="declaring-collections"></a>
+## Declaring Collections
+
+```json
+"collections": [
+    {
+        "name": "ideas",
+        "scope": "room",
+        "schema": {
+            "type": "object",
+            "properties": {
+                "title":  { "type": "string", "maxLength": 120 },
+                "body":   { "type": "string", "maxLength": 2000 },
+                "status": { "type": "string", "enum": ["draft", "posted", "picked"] },
+                "votes":  { "type": "integer", "minimum": 0 }
+            },
+            "required": ["title", "status"]
+        },
+        "indexed": ["status", "votes"],
+        "quota": { "max_records": 500, "max_bytes": 16384 },
+        "permissions": { "update": "owner", "delete": "facilitator" }
+    }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `name` | Required. `^[a-z][a-z0-9_]*$`, max 40, unique. |
+| `scope` | Required. `attempt`, `user`, `room` or `applet`. |
+| `schema` | Required. JSON Schema, `type: "object"`. |
+| `indexed` | Optional, max 8 paths. Each must be a scalar property declared in the schema. Dotted paths allowed. |
+| `quota` | Optional. `max_records`, `max_bytes` — ceilings you may lower, never raise. |
+| `permissions` | Optional. `update` and `delete`: `owner` (default), `members`, `facilitator`. |
+
+<a name="scopes"></a>
+## Scopes
+
+The scope answers, at declaration time, the otherwise ambiguous question of who shares a record and
+what happens to it when an attempt ends.
+
+| Scope | Shared by | Lifetime | Requires |
+|---|---|---|---|
+| `attempt` | One attempt | **Frozen when the attempt completes**, alongside `state` | `attempt@1` |
+| `user` | One participant | Outlives any attempt | — |
+| `room` | Everyone in the room | The room | `broadcast@1` |
+| `applet` | Everyone on this applet version | The version. Read-mostly: seed data, shared catalogs | — |
+
+A session that has no attempt or no room cannot touch a collection scoped to one; the call is
+refused with `forbidden` rather than silently falling back to something else.
+
+<a name="reading-and-writing"></a>
+## Reading and Writing
+
+```ts
+const ideas = Rack.db.collection<Idea>('ideas');
+
+const created = await ideas.create({ title, status: 'draft', votes: 0 });
+const idea    = await ideas.get(created.data.record.id);
+
+await ideas.update(id, { status: 'posted' });          // merges by default
+await ideas.update(id, next, { merge: false });        // replaces the document
+await ideas.delete(id);
+```
+
+Every call resolves to an `AckResult`. A record comes back as:
+
+```ts
+interface RecordRow<T> {
+    id: string;            // uuid
+    data: T;
+    owner_id: number;      // the participant who created it
+    created_at: string;
+    updated_at: string;
+}
+```
+
+Writes are validated against the declared schema **after** the merge, so a partial update that would
+produce an invalid document is refused with `validation` and `details` naming the offending path.
+
+<a name="queries"></a>
+## Queries
+
+```ts
+const { data } = await ideas.list({
+    where: [['status', '=', 'posted'], ['votes', '>=', 3]],
+    orderBy: 'votes',
+    direction: 'desc',
+    limit: 50,
+});
+
+data.records;      // RecordRow<Idea>[]
+data.nextCursor;   // pass back as { cursor } for the next page
+```
+
+```ts
+const { data } = await ideas.count({ where: [['status', '=', 'draft']] });
+```
+
+Operators: `=`, `!=`, `<`, `<=`, `>`, `>=`, `in`.
+
+**Filtering and ordering work only on `indexed` paths.** That is not a limitation the SDK could hide
+— it reflects how the data is actually stored (see below). Decide your query paths when you declare
+the collection, and if you find yourself wanting a ninth index, the shape is probably wrong.
+
+The page size caps at 100 (`ziprack-db.list_limit`). Lists are always scoped: you cannot read
+another room's records, another participant's `user` records, or another attempt's records, because
+the scope id is resolved from the session, never from your payload.
+
+<a name="permissions"></a>
+## Permissions
+
+Reads are scoped; writes are also owned. By default only the creator may update or delete a record.
+
+| Value | Who may |
+|---|---|
+| `owner` | The participant who created it. The default. |
+| `members` | Anyone who can see it — everyone in the room, for a `room` collection. |
+| `facilitator` | The owner, plus whoever currently holds the facilitator role. |
+
+Moderation of a shared board is `"delete": "facilitator"`. A genuinely collaborative document is
+`"update": "members"`. Anything stricter than `owner` does not exist, because scope already decides
+visibility.
+
+<a name="quotas"></a>
+## Quotas
+
+Declared quotas are enforced server-side regardless of what the applet believes:
+
+| Limit | Default | Hard ceiling |
+|---|---|---|
+| `max_records` per scope | 500 | 5000 (`ziprack-db.max_records_per_scope`) |
+| `max_bytes` per record | 16 KB | 64 KB (`ziprack-db.max_record_bytes`) |
+
+Over quota, `create()` returns `quota_exceeded`. Handle it — a shared board hitting its cap during a
+live session is a real event, not a theoretical one.
+
+<a name="how-it-is-stored"></a>
+## How It Is Stored
+
+Worth knowing, because it explains the constraints above.
+
+Each collection gets its own MySQL table, created when the applet version installs. The document
+lives in a JSON column; every path in `indexed` becomes a **generated column with an index on it**.
+The declared schema is therefore also the index plan, which is what makes MySQL a good fit here
+rather than a compromise — the queryable paths are known at install time, so there is no need for
+containment queries over undeclared keys.
+
+**Installing a version is a schema-bearing operation.** Adding a collection creates a table; adding
+an indexed path adds a generated column; removing one drops it. Collections that no current manifest
+declares any more are left in place until you run:
+
+```sh
+php artisan ziprack:db:prune
+```