@vibes.diy/prompts 2.4.8 → 2.4.9

package/llms/fireproof.md

@@ -4,11 +4,13 @@ Fireproof is a lightweight embedded document database with encrypted live sync,
 
 ## Key Features
 
-- **Apps run anywhere:** Bundle UI, data, and logic in one file.
+- **Apps run anywhere:** Bundle UI, data, and logic together.
 - **Real-Time & Offline-First:** Automatic persistence and live queries, runs in the browser - no loading or error states.
 - **Unified API:** TypeScript works with Deno, Bun, Node.js, and the browser.
 - **React Hooks:** Leverage `useLiveQuery` and `useDocument` for live collaboration. Note: these are NOT top-level exports — they are returned by the `useFireproof()` hook. Always destructure from `const { useLiveQuery, useDocument, database } = useFireproof("db-name")`.
 
+**File structure:** A vibe's source is one or more files. `/App.jsx` is the entry point (React component). `/access.js` is optional — include it when the app needs per-document write validation or channel-based read isolation. Both files are pushed together and the server discovers `/access.js` automatically.
+
 Fireproof enforces cryptographic causal consistency and ledger integrity using hash history, providing git-like versioning with lightweight blockchain-style verification. Data is stored and replicated as content-addressed encrypted blobs, making it safe and easy to sync via commodity object storage providers.
 
 ## Installation
@@ -271,71 +273,253 @@ Each capability (`read`, `write`, `delete`) is independent. Omitting one falls b
 
 ---
 
-## Multi-Space Pattern: Owner Creates, Members Discover
+## Access Function (`/access.js`)
 
-`listDbNames()` is owner-only — members can't enumerate databases by name. Instead, the owner writes registry documents into a shared database that all members can query to discover available spaces.
+The `acl` option above is a coarse per-database gate. Access functions are a finer gate: functions the server runs on every write (including deletes) before storing the document. They validate writes, route documents to channels, and declare grants that control who can read what. Only create an `/access.js` file when the user asks for per-document routing, channel-based isolation, or document-level write validation.
 
-```jsx
-import { useFireproof, useViewer } from "use-vibes";
-import { fireproof } from "use-fireproof";
-import { useState } from "react";
+Access functions live in `/access.js`, a separate file in the vibe's filesystem alongside `/App.jsx`. Each **named export** maps to a database name — `export function chat(...)` gates `useFireproof("chat")`. An `export default` function acts as a catch-all: it gates any database that doesn't have its own named export. Named exports always take precedence over the default.
 
-export default function App() {
-  const [activeSlug, setActiveSlug] = useState(null);
-  return activeSlug ? (
-    <SpaceView slug={activeSlug} onBack={() => setActiveSlug(null)} />
-  ) : (
-    <SpaceList onSelectSpace={setActiveSlug} />
-  );
+```js
+// /access.js — each export name = the database it gates
+export function chat(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "authentication required" };
+  if (doc.type === "message") {
+    if (doc.userHandle !== user.userHandle) throw { forbidden: "not author" };
+    ctx.requireAccess(doc.channelId);
+    return { channels: [doc.channelId] };
+  }
+  return {};
+}
+```
+
+```js
+// /App.jsx — no access option needed; the server matches by database name
+const { useLiveQuery, database } = useFireproof("chat");
+```
+
+### Function signature
+
+```ts
+(doc, oldDoc, user: UserContext | null, ctx: Helpers) => AccessDescriptor;
+```
+
+- `doc` — the document being written
+- `oldDoc` — the previous version (null for new documents)
+- `user` — the authenticated user, or `null` for anonymous requests
+- `ctx` — server-provided helpers for checking materialized state
+
+**UserContext:**
+
+```ts
+{
+  userHandle: string    // stable unique id — use for all auth checks
+  displayName?: string  // display only — never use for identity checks
 }
+```
+
+**Helpers (`ctx`):** Opaque closures over the materialized grant state. They throw or pass — you cannot enumerate channels, list members, or iterate grants. Both helpers also throw when `user` is null.
+
+- `ctx.requireAccess(channelId)` — throws if user is not in the channel
+- `ctx.requireRole(roleName)` — throws if user is not in the role
+
+### AccessDescriptor return type
+
+All fields are optional. `{}` is a valid return. `throw { forbidden: "reason" }` rejects the write.
+
+```ts
+type AccessDescriptor = {
+  channels?: string[]; // route this doc to channels
+  members?: Record<roleName, userHandle[]>; // role membership (reduced by union)
+  grant?: {
+    users?: Record<userHandle, string[]>; // direct user → channel grants (reduced by union)
+    roles?: Record<roleName, string[]>; // role → channel grants (reduced by union)
+    public?: string[]; // public read — no auth required
+  };
+  expiry?: string | number | null; // ISO date or unix seconds
+  allowAnonymous?: boolean; // opt-in for null-user writes
+};
+```
+
+### Key concepts
+
+**Channels** route documents. A document with `channels: ["general"]` is only visible to users who have been granted access to `"general"`. Channels are the unit of read isolation.
+
+**Grants are additive.** The effective access state is the union of every current document's `AccessDescriptor` output. There is no "remove grant" operation — deleting a document drops its contribution from the union automatically. This makes revocation trivial: delete the document that granted access, and the grant disappears on next sync.
+
+**Grant resolution order:** The server resolves per-user channel access in two passes — first expand `grant.roles` through `members`, then union with `grant.users` direct grants.
 
-function SpaceList({ onSelectSpace }) {
-  const viewer = useViewer();
-  // No explicit ACL on the registry — app-level defaults let all members read
-  const { database: registry, useLiveQuery } = useFireproof("spaces-registry");
-  const { docs: spaces } = useLiveQuery("type", { key: "space", descending: true });
+**`allowAnonymous` prevents a footgun.** If `user` is `null` and the function returns without throwing, the runtime checks `allowAnonymous`. If absent or `false`, the write is rejected. This prevents a function that never inspects `user` from silently opening anonymous writes. When `user` is not null, `allowAnonymous` has no effect. `grant.public` grants public _read_; anonymous _write_ requires `allowAnonymous: true` separately.
 
-  async function createSpace(name, slug, acl) {
-    await registry.put({ type: "space", name, slug, acl, userSlug: viewer?.userSlug, createdAt: Date.now() });
-    // Declares the ACL server-side — owner-only; silently ignored for non-owners
-    fireproof(slug).applyAcl(acl);
+**Access functions are server-enforced policy code.** Checks should be deterministic over `(doc, oldDoc, user, ctx)` and deny with `throw { forbidden: "reason" }` when violated.
+
+### Example: Workspace chat with channels
+
+```js
+// /access.js
+export function chat(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "authentication required" };
+
+  if (doc.type === "channel-meta") {
+    if (doc.ownerHandle !== user.userHandle) throw { forbidden: "not owner" };
+    if (oldDoc && oldDoc.ownerHandle !== user.userHandle) throw { forbidden: "not owner" };
+    return {
+      channels: [doc._id],
+      grant: {
+        users: Object.fromEntries([[doc.ownerHandle, [doc._id]], ...doc.memberHandles.map((h) => [h, [doc._id]])]),
+      },
+    };
   }
 
-  return (
-    <div>
-      <ul>
-        {spaces.map((s) => (
-          <li key={s._id}>
-            <button onClick={() => onSelectSpace(s.slug)}>{s.name}</button>
-          </li>
-        ))}
-      </ul>
-      <button onClick={() => createSpace("Announcements", "space-announcements", { write: ["editors"], delete: ["editors"] })}>
-        + Create Space
-      </button>
-    </div>
-  );
+  if (doc.type === "message") {
+    if (doc.userHandle !== user.userHandle) throw { forbidden: "not author" };
+    ctx.requireAccess(doc.channelId);
+    return { channels: [doc.channelId] };
+  }
+
+  if (doc.type === "channel-invite") {
+    if (doc.senderHandle !== user.userHandle) throw { forbidden: "not sender" };
+    ctx.requireAccess(doc.channelId);
+    return {
+      channels: [doc.channelId],
+      grant: { users: { [doc.inviteeHandle]: [doc.channelId] } },
+    };
+  }
+
+  return {};
 }
+```
 
-function SpaceView({ slug, onBack }) {
-  const { useLiveQuery, useDocument } = useFireproof(slug);
-  const { doc, merge, submit } = useDocument({ text: "", type: "message" });
-  const { docs } = useLiveQuery("_id", { descending: true, limit: 50 });
+This single access function handles three document types:
 
-  return (
-    <div>
-      <button onClick={onBack}>← Back</button>
-      <ul>
-        {docs.map((d) => (
-          <li key={d._id}>{d.text}</li>
-        ))}
-      </ul>
-      <form onSubmit={submit}>
-        <input value={doc.text} onChange={(e) => merge({ text: e.target.value })} placeholder="Message…" />
-        <button type="submit">Send</button>
-      </form>
-    </div>
-  );
+- **channel-meta** — owner creates a channel and grants access to listed members
+- **message** — only the author can post, must already have channel access
+- **channel-invite** — any channel member can invite others; deleting the invite revokes the grant
+
+### Example: Anonymous survey with role-gated results
+
+```js
+// /access.js
+export function survey(doc, oldDoc, user, ctx) {
+  if (doc.type === "survey-response") {
+    if (oldDoc) throw { forbidden: "responses are write-once" };
+    return { channels: ["inbound-responses"], allowAnonymous: true };
+  }
+
+  if (doc.type === "survey-config") {
+    ctx.requireRole("survey-admin");
+    return {
+      grant: {
+        roles: {
+          "survey-admin": ["inbound-responses"],
+          "feedback-team": ["inbound-responses"],
+        },
+      },
+    };
+  }
+
+  if (doc.type === "final-results") {
+    ctx.requireRole("feedback-team");
+    return { channels: [doc._id], grant: { public: [doc._id] } };
+  }
+
+  if (!user) throw { forbidden: "authentication required" };
+  return {};
+}
+```
+
+Key patterns:
+
+- `allowAnonymous: true` on survey-response lets unauthenticated visitors submit
+- Requiring `doc._id` to be falsy prevents clients from choosing or overwriting response IDs
+- `grant.public` on final-results makes them readable without authentication
+- The **singleton grant doc** pattern (survey-config) wires role-to-channel access in one place
+
+### Multiple databases in one file
+
+Each named export gates its own database. A single `/access.js` can gate all databases the app uses:
+
+```js
+// /access.js
+export function chat(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "authentication required" };
+  ctx.requireAccess(doc.channelId);
+  return { channels: [doc.channelId] };
+}
+
+export function notes(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "authentication required" };
+  return {};
+}
+```
+
+Databases without a matching named export fall through to `export default` if one exists. If there is no default export either, the database uses the default app-level permissions (no access function).
+
+### Catch-all with `export default`
+
+Use `export default` to gate every database without writing a named export for each one. Named exports still take precedence for databases that need custom logic:
+
+```js
+// /access.js
+export function chat(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "authentication required" };
+  ctx.requireAccess(doc.channelId);
+  return { channels: [doc.channelId] };
+}
+
+// Everything else: require authentication, no channel routing
+export default function (doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "authentication required" };
+  return {};
+}
+```
+
+This is especially useful when an app has many databases or uses hyphenated names (`error-log`, `user-prefs`) that can't be JavaScript identifiers.
+
+### Roles via `members` reduce
+
+Roles are not a fixed registry. They are materialized from document contributions:
+
+```js
+// A team-meta doc contributes members to a role
+if (doc.type === "team-meta") {
+  ctx.requireRole("admin");
+  return {
+    members: { [doc.teamId]: doc.memberHandles },
+    grant: { roles: { [doc.teamId]: doc.channels } },
+  };
+}
+
+// A per-employee membership doc contributes one handle
+if (doc.type === "membership") {
+  return { members: { [doc.role]: [doc.userHandle] } };
+}
+```
+
+Both patterns produce identical reduced state. Deleting a membership doc removes the user from the role automatically.
+
+### Common `oldDoc` patterns
+
+Use `oldDoc` (the previous version of the document) to enforce invariants across updates:
+
+```js
+// New document (create)
+if (oldDoc === null) {
+  // create-only logic
+}
+
+// Immutable-after-create fields
+if (oldDoc && doc.createdBy !== oldDoc.createdBy) {
+  throw { forbidden: "createdBy is immutable" };
+}
+
+// Prevent unauthorized ownership transfer
+if (oldDoc && oldDoc.ownerHandle !== user.userHandle) {
+  throw { forbidden: "not owner" };
+}
+
+// Monotonic version — can only increase
+if (oldDoc && doc.version <= oldDoc.version) {
+  throw { forbidden: "version must increase" };
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "2.4.8",
+  "version": "2.4.9",
   "type": "module",
   "main": "./index.js",
   "description": "",
@@ -30,8 +30,8 @@
     "@fireproof/core-types-base": "~0.24.19",
     "@fireproof/core-types-protocols-cloud": "~0.24.19",
     "@fireproof/use-fireproof": "~0.24.19",
-    "@vibes.diy/call-ai-v2": "^2.4.8",
-    "@vibes.diy/use-vibes-types": "^2.4.8",
+    "@vibes.diy/call-ai-v2": "^2.4.9",
+    "@vibes.diy/use-vibes-types": "^2.4.9",
     "arktype": "~2.2.0",
     "json-schema-faker": "~0.6.1"
   },