@exposify/firebase 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Exposify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,174 @@
-# Temporary Holding Version
+# @exposify/firebase: setup guide
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Make a Firebase app usable by AI agents: one Cloud Function serves MCP, with
+tools for the Firestore collections you name, the callable functions you
+register, and your bundled docs. The caller's Firebase ID token goes
+straight to the Firestore REST API, so **your Security Rules are the
+authorization layer**. The agent can do exactly what that signed-in user can
+do from your app, nothing more. The function never uses the Admin SDK.
+
+For the design rationale, see
+`docs/superpowers/specs/2026-10-10-exposify-firebase-design.md` in the repo
+root.
+
+## Prerequisites
+
+- A Firebase project with Cloud Functions (`firebase init functions`; Node 20+,
+  TypeScript or JavaScript) and Firestore.
+- The Firebase CLI for `firebase deploy`.
+
+## 1. Scaffold
+
+From your Firebase project root (where `firebase.json` is):
+
+```bash
+npx exposify-firebase init
+```
+
+It reads `firebase.json` to find your functions directory and
+`firestore.rules` to propose collections, then:
+
+- writes `functions/src/mcp.ts` (or `mcp.js` for JavaScript projects): the
+  MCP function, with every collection found in your rules listed as
+  readable and all writes commented out;
+- adds `export { mcp } from "./mcp.js";` to your functions entry file.
+
+It never overwrites an existing `mcp.ts`, so re-running is safe. `--dry-run`
+prints the plan without writing.
+
+The rules reading is a proposal, not an analysis: a `match /todos/{id}`
+block becomes the `todos` collection, and a rule like
+`resource.data.uid == request.auth.uid` becomes `owner: "uid"`. Review the
+list before deploying.
+
+## 2. Install and deploy
+
+```bash
+cd functions && npm install @exposify/firebase
+firebase deploy --only functions:mcp
+```
+
+## 3. Connect an agent
+
+Point an MCP client at the function's URL
+(`https://<region>-<project>.cloudfunctions.net/mcp`) with the header
+`Authorization: Bearer <Firebase ID token>`. In your app,
+`await auth.currentUser.getIdToken()` returns one. ID tokens expire after an
+hour, so this is good for a quick try, not a lasting connection.
+
+Without a token, Firestore evaluates rules with `request.auth == null`, so
+the agent gets whatever your rules allow anonymous users.
+
+### Lasting connections: the hosted broker
+
+Set `EXPOSIFY_KEY` (the secret key from your project in the Exposify
+dashboard) in the function's environment and the broker turns on by itself,
+with no code change. Users then sign in from their MCP client: a request
+without a connection gets a `401` that points the client at
+`<function URL>/.well-known/oauth-protected-resource`, which names the
+broker as the authorization server, and the client sends the user through
+sign-in. Tool calls then reach Firestore with the `Authorization` the broker
+resolves for that user, never the broker token itself, so your rules still
+decide. Requests without a connection are refused rather
+than run anonymously; pass `authRequired: false` to allow them.
+
+`auth: hostedBroker()` does the same explicitly. If the function is
+reached through a URL other than the one it sees (a custom domain or a
+Hosting rewrite), set it with `hostedBroker({ resource: "https://…/mcp" })`.
+Behind `*.cloudfunctions.net/<name>` and `*.run.app` the right URL is worked
+out for you. See [`docs/hosted-broker.md`](../../docs/hosted-broker.md).
+
+## Configuration
+
+```ts
+import { onRequest } from "firebase-functions/v2/https";
+import { aiReady } from "@exposify/firebase";
+
+export const mcp = onRequest(
+  aiReady({
+    collections: {
+      todos: {
+        description: "The user's todo items",
+        owner: "uid",
+        fields: {
+          title: { type: "string" },
+          done: { type: "boolean" },
+          due: { type: "string", format: "date-time" },
+        },
+        required: ["title"],
+      },
+      "users/{userId}/notes": {},
+    },
+    writes: ["todos.*", "users/{userId}/notes.create"],
+    functions: {
+      refundOrder: {
+        description: "Refund an order. Reversible within 30 days.",
+        input: { properties: { orderId: { type: "string" } }, required: ["orderId"] },
+      },
+    },
+  }),
+);
+```
+
+| Option | Default | What it does |
+|---|---|---|
+| `collections` | none | Collections agents can use, keyed by path. `{param}` placeholders make subcollections; each becomes a tool argument. An array of names is shorthand for no per-collection config. |
+| `collections[k].fields` | none | Field schema (a JSON Schema subset). Limits filters and `select` to these names and types writes. `format: "date-time"` stores a string as a Firestore timestamp. Without it, any field name and any object are accepted. |
+| `collections[k].owner` | none | The field holding the owner's uid. `list_*` filters on it, `create_*` sets it from the token, `update_*` refuses to change it. |
+| `writes` | `[]` | `"<collection>.create"`, `.update`, `.delete` or `.*`. |
+| `functions` | `{}` | Callable functions (`onCall`), invoked with the caller's token. `url` overrides the address. |
+| `functionsRegion` | `us-central1` | Region of those callable functions. |
+| `docs` | `["docs/**/*.md"]` | Markdown files, relative to the functions directory, served through `search_docs`. |
+| `docsAuth` | `"public"` (`"required"` with the hosted broker) | `"required"` hides `search_docs` from callers without a token. |
+| `maxDocs` | `100` | Cap on documents per `list_*` call. |
+| `projectId`, `databaseId` | from the environment, `(default)` | Set automatically in deployed functions. |
+| `auth`, `authRequired` | the hosted broker when `EXPOSIFY_KEY` is set, else none | A resolver that turns the incoming headers into the ones sent to Firebase (e.g. `hostedBroker()`, Exposify's hosted broker), and whether a missing result is a 401 (default: true with the hosted broker, false otherwise). |
+
+## Tools
+
+For each collection (tool names use the collection ids, snake_cased:
+`users/{userId}/notes` → `users_notes`):
+
+- `list_<c>`: `where` (operators as in the client SDK: `==`, `!=`, `<`, `<=`,
+  `>`, `>=`, `array-contains`, `in`, `not-in`, `array-contains-any`),
+  `orderBy`, `limit`, `select`.
+- `get_<c>`: one document by `id`.
+- `create_<c>`, `update_<c>`, `delete_<c>`: only when opted in. Updates and
+  deletes take one document id; there are no bulk writes. Updates change
+  only the given fields and fail if the document doesn't exist.
+- `call_<fn>`: each registered callable function.
+- `search_docs`: when docs are bundled.
+
+Documents come back as `{ id, path, data, createTime, updateTime }`, with
+timestamps as ISO strings and references as document paths.
+
+Errors from Firestore reach the agent as they are (`HTTP 403: Missing or
+insufficient permissions`, or a missing-index error with the link to create
+the index), so it can correct its call. 5xx errors are replaced by a generic
+message.
+
+## Common rule shapes
+
+- **Owner field** (`allow read: if resource.data.uid == request.auth.uid`):
+  set `owner: "uid"`. Firestore rejects a query that doesn't filter on the
+  field, so without `owner` the agent has to add the filter itself (the 403
+  it gets says so).
+- **Per-user subcollection** (`match /users/{userId}/notes/{id}` with
+  `request.auth.uid == userId`): key the collection
+  `"users/{userId}/notes"`; the agent passes its own uid as `userId`.
+
+## Local testing with the emulators
+
+Under `firebase emulators:start --only functions,firestore`, the Functions
+emulator sets `FIRESTORE_EMULATOR_HOST`, so the MCP function talks to the
+Firestore emulator and its rules. The function's URL is
+`http://127.0.0.1:5001/<project>/us-central1/mcp`. The emulator accepts
+unsigned ID tokens, which is how this package's integration test runs two
+users against real rules (`test/integration/`).
+
+## Not supported yet
+
+Realtime Database, Storage, collection-group queries, transactions and
+batched writes, pagination cursors, inferring field schemas from existing
+documents, and the `oauth` option (Firebase Auth isn't an OAuth
+authorization server).

package/dist/cli.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+// bin/init.ts
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+
+// bin/rules.ts
+function collectionsFromRules(source) {
+  const text = stripComments(source);
+  const blocks = [];
+  collectBlocks(text, blocks);
+  const out = /* @__PURE__ */ new Map();
+  for (const block of blocks) {
+    const docsAt = block.path.indexOf("documents");
+    if (docsAt === -1) continue;
+    const segments = block.path.slice(docsAt + 1);
+    if (segments.length === 0 || segments.length % 2 !== 0) continue;
+    if (segments.some((s) => /^\{[^}]*=\*\*\}$/.test(s))) continue;
+    const last = segments[segments.length - 1];
+    if (!/^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(last)) continue;
+    const collectionSegments = segments.slice(0, -1).map((seg, i) => i % 2 === 1 ? renameReserved(seg, segments[i - 1]) : seg);
+    if (collectionSegments.some((s, i) => i % 2 === 0 && s.includes("{"))) continue;
+    const key = collectionSegments.join("/");
+    if (out.has(key)) continue;
+    const owner = ownerField(block.body);
+    out.set(key, owner ? { key, owner } : { key });
+  }
+  return [...out.values()];
+}
+function renameReserved(segment, collection) {
+  return segment === "{id}" ? `{${collection.replace(/[^A-Za-z0-9_]/g, "_")}Id}` : segment;
+}
+function ownerField(body) {
+  const m = body.match(/resource\.data\.([A-Za-z_][A-Za-z0-9_]*)\s*==\s*request\.auth\.uid/) ?? body.match(/request\.auth\.uid\s*==\s*resource\.data\.([A-Za-z_][A-Za-z0-9_]*)/);
+  return m?.[1];
+}
+function collectBlocks(text, out) {
+  const stack = [{ block: null, path: [] }];
+  const matchRe = /^match\s+(\/(?:[^\s{]|\{[^}\s]*\})*)\s*\{/;
+  const enclosingBlock = () => {
+    for (let j = stack.length - 1; j >= 0; j--) if (stack[j].block) return stack[j].block;
+    return null;
+  };
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "m" && !/[A-Za-z0-9_.]/.test(text[i - 1] ?? " ")) {
+      const m = text.slice(i, i + 512).match(matchRe);
+      if (m) {
+        const path = [...stack[stack.length - 1].path, ...m[1].split("/").filter(Boolean)];
+        const block2 = { path, body: "" };
+        out.push(block2);
+        stack.push({ block: block2, path });
+        i += m[0].length - 1;
+        continue;
+      }
+    }
+    if (c === "{") {
+      const block2 = enclosingBlock();
+      if (block2) block2.body += c;
+      stack.push({ block: null, path: stack[stack.length - 1].path });
+      continue;
+    }
+    if (c === "}") {
+      const popped = stack.length > 1 ? stack.pop() : null;
+      const block2 = enclosingBlock();
+      if (block2 && !popped?.block) block2.body += c;
+      continue;
+    }
+    const block = enclosingBlock();
+    if (block) block.body += c;
+  }
+}
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/\/\/[^\n]*/g, " ");
+}
+
+// bin/init.ts
+var GENERATED_MARKER = "Generated by `exposify-firebase init`";
+function planInit(root) {
+  const warnings = [];
+  const firebaseJsonPath = join(root, "firebase.json");
+  let firebaseJson = {};
+  if (existsSync(firebaseJsonPath)) {
+    try {
+      firebaseJson = JSON.parse(readFileSync(firebaseJsonPath, "utf8"));
+    } catch {
+      warnings.push("firebase.json isn't valid JSON; assuming the default functions/ directory and firestore.rules");
+    }
+  } else {
+    warnings.push("no firebase.json here; run this from your Firebase project root (`firebase init functions` creates one)");
+  }
+  const functionsCfg = Array.isArray(firebaseJson.functions) ? firebaseJson.functions.find((f) => !f.codebase || f.codebase === "default") ?? firebaseJson.functions[0] : firebaseJson.functions;
+  const functionsDir = (functionsCfg?.source ?? "functions").replace(/\/+$/, "");
+  const firestoreCfg = Array.isArray(firebaseJson.firestore) ? firebaseJson.firestore[0] : firebaseJson.firestore;
+  const rulesRel = firestoreCfg?.rules ?? "firestore.rules";
+  const pkgPath = join(root, functionsDir, "package.json");
+  let pkg = {};
+  if (existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    } catch {
+      warnings.push(`${functionsDir}/package.json isn't valid JSON`);
+    }
+  } else {
+    warnings.push(`no ${functionsDir}/package.json; run \`firebase init functions\` first`);
+  }
+  if (pkg.dependencies && !pkg.dependencies["firebase-functions"]) {
+    warnings.push(`${functionsDir}/package.json doesn't depend on firebase-functions; the generated file imports it`);
+  }
+  const kind = existsSync(join(root, functionsDir, "tsconfig.json")) ? "ts" : pkg.type === "module" ? "esm" : "cjs";
+  const entryRel = kind === "ts" ? "src/index.ts" : pkg.main ?? "index.js";
+  const entryFile = `${functionsDir}/${entryRel.replace(/^\.\//, "")}`;
+  const entryDir = entryFile.slice(0, entryFile.lastIndexOf("/"));
+  const mcpFile = `${entryDir}/mcp.${kind === "ts" ? "ts" : "js"}`;
+  let collections = [];
+  const rulesPath = join(root, rulesRel);
+  const rulesFile = existsSync(rulesPath) ? rulesRel : null;
+  if (rulesFile) {
+    collections = collectionsFromRules(readFileSync(rulesPath, "utf8"));
+    if (collections.length === 0) warnings.push(`found no collection match blocks in ${rulesRel}; add collections to ${mcpFile} by hand`);
+  } else {
+    warnings.push(`no ${rulesRel}; add collections to ${mcpFile} by hand`);
+  }
+  const actions = [];
+  if (existsSync(join(root, mcpFile))) {
+    actions.push({ kind: "skip", file: mcpFile, reason: "already exists; leaving it as is" });
+  } else {
+    actions.push({ kind: "write", file: mcpFile, reason: "the MCP function", content: mcpSource(kind, collections) });
+  }
+  const entryPath = join(root, entryFile);
+  const entrySource = existsSync(entryPath) ? readFileSync(entryPath, "utf8") : null;
+  if (entrySource === null) {
+    warnings.push(`no ${entryFile}; export mcp from your functions entry file yourself`);
+  } else if (/(['"])\.\/mcp(\.js)?\1/.test(entrySource)) {
+    actions.push({ kind: "skip", file: entryFile, reason: "already exports mcp" });
+  } else {
+    actions.push({ kind: "append", file: entryFile, reason: "export the new function", content: exportLine(kind) });
+  }
+  return { functionsDir, kind, mcpFile, entryFile, rulesFile, collections, actions, warnings };
+}
+function exportLine(kind) {
+  if (kind === "cjs") return 'exports.mcp = require("./mcp").mcp;\n';
+  return 'export { mcp } from "./mcp.js";\n';
+}
+function mcpSource(kind, collections) {
+  const imports = kind === "cjs" ? 'const { onRequest } = require("firebase-functions/v2/https");\nconst { aiReady } = require("@exposify/firebase");\n' : 'import { onRequest } from "firebase-functions/v2/https";\nimport { aiReady } from "@exposify/firebase";\n';
+  const entries = collections.length ? collections.map((c) => `      ${JSON.stringify(c.key)}: {${c.owner ? ` owner: ${JSON.stringify(c.owner)} ` : ""}},`).join("\n") : '      // "todos": { owner: "uid" },';
+  const writes = collections.length ? collections.map((c) => `      // ${JSON.stringify(`${c.key}.*`)},`).join("\n") : '      // "todos.*",';
+  const exportStart = kind === "cjs" ? "exports.mcp = onRequest(" : "export const mcp = onRequest(";
+  return `// ${GENERATED_MARKER}. Yours to edit; re-running init won't overwrite it.
+//
+// Agents connect to this function's URL with a signed-in user's Firebase ID
+// token. Every Firestore call runs as that user, so your Security Rules
+// decide what they can read and write.
+${imports}
+${exportStart}
+  aiReady({
+    // Collections agents can read (list_* and get_* tools). Proposed from
+    // your firestore.rules; remove any agents shouldn't see. \`owner\` is the
+    // field your rules compare to request.auth.uid.
+    collections: {
+${entries}
+    },
+    // Writes are opt-in: uncomment to add create_*, update_* and delete_* tools.
+    writes: [
+${writes}
+    ],
+  }),
+);
+`;
+}
+function applyPlan(root, plan) {
+  for (const action of plan.actions) {
+    const path = join(root, action.file);
+    if (action.kind === "write") {
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, action.content, { flag: "wx" });
+    } else if (action.kind === "append") {
+      appendFileSync(path, `
+${action.content}`);
+    }
+  }
+}
+function nextSteps(plan) {
+  return `Next:
+  1. cd ${plan.functionsDir} && npm install @exposify/firebase
+  2. Review ${plan.mcpFile}: which collections agents see, and which writes to allow.
+  3. firebase deploy --only functions:mcp
+  4. Point an MCP client at the function's URL (the deploy prints it), with a
+     header "Authorization: Bearer <ID token>". In your app,
+     await auth.currentUser.getIdToken() gives you one; it expires after an
+     hour. For long-lived agent access, use Exposify's hosted broker:
+     auth: hostedBroker() with EXPOSIFY_KEY set (see docs/hosted-broker.md).`;
+}
+
+// bin/cli.ts
+var USAGE = `Usage: exposify-firebase init [--dry-run]
+
+Run from your Firebase project root (where firebase.json is). Writes an MCP
+function to your functions source directory, with collections proposed from
+firestore.rules (reads only; writes are commented out), and exports it from
+your functions entry file. Safe to re-run: existing files are left alone.`;
+function main(argv) {
+  const [command, ...flags] = argv;
+  if (command !== "init" || flags.some((f) => f !== "--dry-run")) {
+    console.log(USAGE);
+    return command === "--help" || command === "-h" ? 0 : 1;
+  }
+  const root = process.cwd();
+  const plan = planInit(root);
+  for (const w of plan.warnings) console.warn(`warning: ${w}`);
+  if (plan.collections.length) {
+    console.log(`Collections from ${plan.rulesFile}: ${plan.collections.map((c) => c.key).join(", ")}`);
+  }
+  for (const a of plan.actions) {
+    const verb = a.kind === "write" ? "create" : a.kind === "append" ? "update" : "skip  ";
+    console.log(`  ${verb} ${a.file}  (${a.reason})`);
+  }
+  if (flags.includes("--dry-run")) return 0;
+  try {
+    applyPlan(root, plan);
+  } catch (err) {
+    console.error(`init failed: ${err.message}`);
+    return 1;
+  }
+  console.log(`
+${nextSteps(plan)}`);
+  return 0;
+}
+process.exitCode = main(process.argv.slice(2));