@getxflow/cli 0.3.0 → 0.3.2

package/dist/commands/functions.js

@@ -8,6 +8,12 @@ const config_1 = require("../config");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
 const ui_1 = require("../ui");
+/** Who can call the function: inside the app only, or an outside service holding a key. */
+function accessLabel(fn) {
+    if (!fn.external_keys)
+        return 'in-app only';
+    return `external (${fn.external_keys} key${fn.external_keys > 1 ? 's' : ''})`;
+}
 const FUNCTIONS_DIR = 'functions';
 async function functionsList() {
     const { config } = (0, config_1.requireProject)();
@@ -20,6 +26,7 @@ async function functionsList() {
     (0, ui_1.table)(data.functions.map((fn) => [
         fn.name,
         fn.status === 'deployed' ? 'deployed' : fn.status === 'failed' ? 'failed' : fn.status,
+        accessLabel(fn),
         fn.last_deployed_at ? (0, ui_1.formatAge)(fn.last_deployed_at) : '-',
         fn.error_message ?? '',
     ]));
@@ -49,6 +56,17 @@ async function functionsInvoke(args) {
     const data = (0, args_1.flagString)(args, 'data');
     const method = ((0, args_1.flagString)(args, 'method') ?? (data ? 'POST' : 'GET')).toUpperCase();
     const sendsBody = method !== 'GET' && method !== 'HEAD';
+    // A pass for the person who owns the key: the project token alone is not an
+    // identity, and a project built with the current template refuses without one.
+    // A read-only key cannot get a pass, so the call still goes out without it.
+    let pass = '';
+    try {
+        const issued = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/pass`, { method: 'POST' });
+        pass = issued.pass;
+    }
+    catch {
+        (0, ui_1.note)((0, ui_1.dim)('  Could not get a visitor pass: calling with the project token only'));
+    }
     const started = Date.now();
     let response;
     try {
@@ -57,6 +75,7 @@ async function functionsInvoke(args) {
             headers: {
                 'Content-Type': 'application/json',
                 'X-Project-Token': card.project_token ?? '',
+                ...(pass ? { 'X-Project-Pass': pass } : {}),
             },
             body: sendsBody ? (data ?? '{}') : undefined,
             // Wait past the function's own 90 s cap to see its timeout, not ours.

package/dist/help.js

@@ -150,8 +150,9 @@ A failed run shows up in ${(0, ui_1.bold)('xflow functions logs')}: nobody is wa
 function, so the wrapper reports a crash the same way it does on an ordinary call.`,
     invoke: `${(0, ui_1.bold)('xflow functions invoke')} <name>: call a function
 
-Calls it exactly the way the application does, with the X-Project-Token header. The
-token is taken from the project card on the platform, no local .env is needed.
+Calls it exactly the way the application does: the project token plus a visitor pass
+for the person who owns the key, so the function sees a real caller and its role.
+Both are taken from the platform, no local .env is needed.
 
   --data '{"a":1}'   request body (the method becomes POST by default)
   --method GET       a different method

package/dist/version.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_URL = exports.CLI_VERSION = void 0;
 /** Keep in sync with cli/package.json. */
-exports.CLI_VERSION = '0.3.0';
+exports.CLI_VERSION = '0.3.1';
 /** Overridden by XFLOW_API_URL or the `api` field in xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getxflow/cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {

package/skills/xflow/SKILL.md

@@ -146,13 +146,60 @@ output of that call. Only failed calls are logged, so an empty output means the
 never crashed, not that logging is broken.
 
 From the app, call a function through `src/lib/xflow.ts`:
-`await xflow.functions.invoke('send-mail', { body: { to } })`. It carries the project
-token for you. Addresses are baked into the build, which is why the functions go out first:
+`await xflow.functions.invoke('send-mail', { body: { to } })`. It carries the credentials
+for you. Addresses are baked into the build, which is why the functions go out first:
 by the time the bundle is built they already exist, and a new function is never missing
 from the application that calls it.
 
-Treat a function as a public API: the token ships inside the frontend bundle, so anyone
-who opens the app can call it.
+### Who is calling
+
+A function answers only to a member of the organization who has access to that project.
+The platform issues a short-lived pass when it opens the application, the wrapper checks it
+with the platform on every call, and the handler receives the answer in `event.xflow`:
+
+```js
+exports.handler = async (event) => {
+  const { caller, user } = event.xflow
+  // caller: 'visitor' (a person), 'service' (another function of this project),
+  //         'external' (an outside service with a key), 'schedule' (a timer run)
+  // user:   { id, role } for a visitor, null for everything else
+}
+```
+
+Never trust an identity that arrives in the body or in a header of the request: those are
+written by the page, which lives on someone else's computer. `event.xflow` is the only
+identity the platform stands behind, and `usePlatformAuth()` in the frontend is a hint for
+the interface, not a check.
+
+A function that changes data should say so instead of checking the role by hand:
+
+```js
+exports.minRole = 'admin'   // 'member' | 'developer' | 'admin' | 'owner'
+```
+
+The wrapper refuses anything below that role before your code runs. Without the line every
+member of the project can call the function, including the ones who may only look at apps.
+
+Losing access closes the function within five minutes, so a removed member cannot keep calling it.
+Opening the deployed address directly does not work either: there is no pass outside the
+platform.
+
+Calling a function from another function is a server call. Send two headers, both from the
+environment the platform fills in: `X-Project-Token` with `process.env.XFLOW_PROJECT_TOKEN`
+and `X-Server-Key` with `process.env.XFLOW_SERVER_KEY`. The token is the ticket into the
+project and the key is the identity; the wrapper checks the ticket first, so the key alone
+answers 401.
+
+An outside service (a webhook from a payment provider, a bot, a CRM) has no person behind it
+and needs a key of that one function. Keys are not issued by default and the CLI cannot
+create one: a human issues it in the project settings: «Облачные функции» → the function →
+«Настройки». Ask the user to do that and to paste the address back to you — never invent
+another way in. A function holds at most two keys, and the second one exists to replace the
+first without downtime, not to serve a second consumer.
+
+`xflow functions list` shows who can reach each function: `in-app only` (no keys, answers
+only inside the application) or `external (N keys)` (a human issued external access). Key
+values are never shown there.
 
 Keys and passwords live on the platform, not in the repository: `xflow env set SMTP_PASSWORD=…`
 writes one, `xflow env` lists the names, `xflow env check` tells you which variables your
@@ -160,8 +207,9 @@ functions read but the platform does not have. Values never come back out — th
 they exist is inside the running function.
 
 A function receives only the variables it mentions by name via `process.env.NAME`, so never
-assemble a variable name from an expression. New values arrive on the next `xflow deploy`,
-not at the moment they are written.
+assemble a variable name from an expression and never destructure the environment
+(`const { API_KEY } = process.env` reads as no mention at all, and the variable arrives
+empty). New values arrive on the next `xflow deploy`, not at the moment they are written.
 
 To run a function on a timer: `xflow schedules set report "0 3 ? * * *"` (daily at 03:00).
 Six fields, UTC, and exactly one of day-of-month / day-of-week must be `?` — that is
@@ -184,7 +232,9 @@ const db = new Client({ connectionString: process.env.DATABASE_URL })
 
 The platform passes `DATABASE_URL` only to functions that mention it, and sets the project
 schema on every connection, so plain table names (`select * from tasks`) hit your project.
-You never write that variable yourself: `xflow env set DATABASE_URL=...` is refused.
+You never write that variable yourself: `xflow env set DATABASE_URL=...` is refused. The same
+goes for every name starting with `XFLOW`: the platform fills those in itself, and your value
+under one of them would shadow the real one.
 
 The platform keeps no database history and no backups. Anything that destroys data
 (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) is refused
@@ -195,6 +245,57 @@ One logical database can be shared by several projects, so your migration can br
 you do not see. `xflow db status` lists applied migrations that have no file in your
 repository: that is what someone else's project did.
 
+## File storage
+
+The project has file storage, and the browser cannot reach it. Those endpoints take only the
+server key of the project, and the platform puts it into the environment of your cloud
+functions as `XFLOW_SERVER_KEY`. Nothing else holds it: not the bundle, not `.env`, not
+`xflow env`.
+
+So uploading is a function of your own. It asks the platform for a one-time link, the browser
+then sends the bytes straight to storage, and a second call records the file:
+
+```js
+const link = await fetch(`${process.env.XFLOW_API_URL}/api/storage/project/upload-url`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Server-Key': process.env.XFLOW_SERVER_KEY,
+  },
+  body: JSON.stringify({ fileName, fileSize, contentType, folderPath: 'invoices' }),
+}).then((r) => r.json())
+```
+
+`confirm` takes the same fields plus the returned `s3Key` and answers with the file and its
+public address; `delete` takes the file `url`. Never pipe the bytes through the function itself.
+
+There is no endpoint that lists the files back, so the address that `confirm` returns is the
+only copy you get: write it into a table of your own in the same call, and the application
+reads its files from there.
+
+Four things bite an upload that otherwise looks right, and none of them is obvious from the
+answers you get:
+
+- **The content type can quietly split in two.** Nothing checks that the `Content-Type` the
+  browser sends on the PUT matches the one you named in `upload-url`: both calls answer 200.
+  But storage keeps the header the browser sent and serves the file under it, while the
+  record keeps the one you named, so a card can say `image/png` about a file every browser
+  treats as HTML. Send the same string in both calls and they cannot drift.
+- **The same name in the same folder is refused.** Names are unique per folder, so a second
+  `avatar.png` fails instead of replacing the first. Give the name a suffix of your own, or
+  delete the old file before confirming the new one.
+- **The limits are 200 MB per file and the storage quota of the organization.** The quota is
+  checked again on `confirm`, by the real size, which means a refusal can land after the
+  bytes are already up; the platform then removes the object and your table stays clean.
+- **Confirm only after the PUT has finished.** The platform looks the object up in storage
+  and takes its real size from there, not from what you declared, so an early `confirm`
+  answers that the file is not there.
+
+What the app may do with files is decided inside that function, because the page in the
+browser can be edited by whoever opened it. Never write the key into the sources and never
+send it to the frontend: the build gate stops on a key found in the application code, and a
+key that reached a visitor lets them delete every file of the project.
+
 ## Syncing code
 
 `xflow status` shows how the local copy differs from the server revision.
@@ -244,7 +345,9 @@ the design system sits in the project.
 
 The app runs inside the platform in an iframe and receives the theme and the current
 user from it. The `usePlatformAuth()` hook gives the name, role, permissions and the
-list of organization members.
+list of organization members. Use it to draw the interface, never to guard data: the
+value lives on the page and is edited from the console. Guard data in the function, by
+`event.xflow`.
 
 ## Errors from a deployed app
 
@@ -256,6 +359,10 @@ records per project are kept.
 Local `npm run dev` does not report anything: these logs exist for what you cannot open
 in your own devtools.
 
+Cloud functions do work under `npm run dev`, and nothing has to be configured for that:
+the dev server swaps the access key of the logged-in developer for the same narrow pass and
+forwards the call. If it answers that the key is missing, the fix is `xflow login`.
+
 ## Environment
 
 `VITE_XFLOW_PROJECT_TOKEN` and `VITE_XFLOW_API_URL` are written by the CLI when the