@feltdb/core 0.13.0 → 0.16.0

package/dist/collection.js

@@ -129,7 +129,9 @@ export class Collection {
      * Returns cached results (live-updated).
      */
     async all() {
-        await this.refresh();
+        // A read the authority refused, or could not answer, is raised typed --
+        // never answered from whatever this handle last cached.
+        await this.refresh({ strict: true });
         return [...this.cache];
     }
     /** List records through the canonical application collection API. */
@@ -177,6 +179,9 @@ export class Collection {
                 const page = await this.db.authority_query({
                     collection: this.name,
                     where: entries.map(([field, eq]) => ({ field, eq })),
+                    // The authority requires an ordering. Every match has the same value of an equality-filtered field, so
+                    // ordering by it is a no-op that the authority completes with its record-id tie-breaker: stable pages.
+                    orderBy: [{ field: entries[0][0], direction: 'asc' }],
                     limit: 100,
                     ...(cursor ? { cursor } : {}),
                 });
@@ -375,7 +380,7 @@ export class Collection {
         const key = `${this.name}:${id}`;
         const result = await this.db.get(key);
         if (!result.success) {
-            throw new Error(result.error || `Failed to read record ${id}`);
+            throw runtimeFailure(result, result.error || `Failed to read record ${id}`);
         }
         if (result.data) {
             return JSON.parse(result.data);
@@ -421,7 +426,7 @@ export class Collection {
             const stored = { ...data, id: recordId, __version: 1 };
             const result = await this.db.insert(key, JSON.stringify(stored));
             if (!result.success) {
-                throw new Error(`Insert failed: ${result.error}`);
+                throw runtimeFailure(result, `Insert failed: ${result.error}`);
             }
             await this.publish('insert', key, String(recordId), null, stored);
             return String(recordId);
@@ -614,9 +619,11 @@ export class Collection {
         const result = await this.db.delete(key);
         if (!result.success) {
             const message = `Delete failed: ${result.error}`;
-            throw /not found/i.test(String(result.error))
-                ? new FeltDBServiceError(message, FeltDBErrorCode.NOT_FOUND)
-                : new Error(message);
+            throw result.cause
+                ? runtimeFailure(result, message)
+                : /not found/i.test(String(result.error))
+                    ? new FeltDBServiceError(message, FeltDBErrorCode.NOT_FOUND)
+                    : new Error(message);
         }
         // Update indexes - find and remove the deleted record
         const deleted = await this.get(id);
@@ -686,7 +693,7 @@ export class Collection {
                 throw error;
             const existing = await this.db.get(key);
             if (!existing.success) {
-                throw new Error(existing.error || `could not read the record that won ${key}`);
+                throw runtimeFailure(existing, existing.error || `could not read the record that won ${key}`);
             }
             if (!existing.data) {
                 throw new Error(`${key} was created and then removed while resolving a conditional create`);
@@ -914,7 +921,7 @@ export class Collection {
     /**
      * Refresh data from the database and notify subscribers.
      */
-    async refresh() {
+    async refresh(options = {}) {
         try {
             // The revision is read *before* the query, so it can only ever be older
             // than the data it ends up labelling. The reverse ordering would let a
@@ -980,14 +987,32 @@ export class Collection {
                 }
             }
             else if (!result.success) {
+                if (options.strict)
+                    throw runtimeFailure(result, result.error || `Failed to read ${this.name}`);
                 console.error('Query failed:', result.error);
             }
         }
         catch (err) {
+            if (options.strict)
+                throw err;
             console.error('Refresh error:', err);
         }
     }
 }
+/**
+ * The error a failed runtime result is raised as. A remote runtime attaches
+ * the authority's typed refusal (`cause`): its stable code, status, request id
+ * and body travel on, so an unauthenticated, cross-application or interrupted
+ * operation is never a bare `Error` with the code only in its message.
+ */
+function runtimeFailure(result, message) {
+    const cause = result.cause;
+    if (!(cause instanceof FeltDBServiceError))
+        return new Error(message);
+    const error = new FeltDBServiceError(message, cause.code, cause.requestId, cause.status, cause.body);
+    error.cause = cause;
+    return error;
+}
 /**
  * Relationship helper for loading related data.
  */

package/dist/create/build-identity.json

@@ -1,13 +1,13 @@
 {
   "schema": "feltdb.build-identity.v2",
   "package": "create-feltdb",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "git": {
-    "sha1": "b67312f73ea647ffea6f87337303c170d40d541d",
+    "sha1": "2433b73d6e643c8476de7e3364350af0230f47be",
     "dirty": false
   },
   "path_in_vcs": "tools/create-feltdb",
-  "source_digest": "sha256:7435af3423598673fcce76eb77444ee1e160f39f3fd83a0a788517e315bd3444",
+  "source_digest": "sha256:8bc6dd69a986ac9db9b709570851ebbdf8cdd9ecf2f61e60d21bb8b5c5f1ed9e",
   "inputs": [
     "Cargo.lock",
     "Cargo.toml",
@@ -20,7 +20,15 @@
     "tools/cli",
     "tools/create-feltdb"
   ],
-  "files": 776,
+  "files": 792,
+  "release": {
+    "tag": "v0.16.0",
+    "ref": "main",
+    "origin_main": {
+      "sha1": "2433b73d6e643c8476de7e3364350af0230f47be",
+      "contains_commit": true
+    }
+  },
   "build": {
     "command": "npm run build",
     "node": "v24.9.0"

package/dist/create/cli.js

@@ -226,7 +226,7 @@ Deployment Target (Explicit):
 
   --managed               Managed FeltDB runtime
                           Best for: Production without operating servers
-                          Requires VITE_FELTDB_URL and VITE_FELTDB_API_KEY
+                          Requires VITE_FELTDB_URL; server-side FELTDB_TOKEN only
 
 Options:
   --browser                Explicit: Browser runtime with IndexedDB

package/dist/create/create.js

@@ -1259,10 +1259,9 @@ main().catch(console.error);
   # FeltDB Server URL (self-hosted or managed runtime)
   VITE_FELTDB_URL=http://localhost:7700
 
-  # Optional credential for authenticated remote browser access
-  VITE_FELTDB_TOKEN=
-  # Legacy alias accepted by older tooling
-  VITE_FELTDB_API_KEY=
+  # Browser code authenticates users with db.auth.signIn() (end-user sessions).
+  # Never put a FeltDB service key (fdb_live_…) in a VITE_ variable: Vite
+  # inlines every VITE_* value into the browser bundle.
 
   # Managed example: https://runtime.your-app.feltdb.com
   VITE_FELTDB_MANAGED_URL=
@@ -1508,7 +1507,7 @@ npm run feltdb:import
 
 ### Self-Hosted
 - \`VITE_FELTDB_URL\`: Docker container URL (default: http://localhost:7700)
-- \`VITE_FELTDB_API_KEY\`: API token for authentication
+- \`FELTDB_TOKEN\`: API key for server-side code only (never a \`VITE_\` variable; browsers use \`db.auth.signIn()\`)
 - \`FELTDB_IMAGE\`: Docker image to use (optional override)
 - \`DOCKER_NETWORK\`: Custom Docker network (optional)
 
@@ -1701,7 +1700,6 @@ Configuration is in \`feltdb.config.json\`:
 Create a \`.env.local\` file (copy from \`.env.example\`):
 
 \`\`\`
-VITE_FELTDB_API_KEY=your_api_key_here
 VITE_FELTDB_URL=http://localhost:7700
 VITE_FELTDB_MANAGED_URL=https://api.feltdb.com
 VITE_FELTDB_MANAGED_APPLICATION_ID=your_application_id

package/dist/create/managed-account.js

@@ -1,5 +1,39 @@
 import fs from 'fs';
 import path from 'path';
+/** Deploy-time key: publish and promote contracts of one application. Never the running app's. */
+export const MANAGED_CONTROL_SCOPES = Object.freeze([
+    'application:read', 'application:write', 'application:revision:create',
+    'application:revision:read', 'application:revision:promote',
+    'application:environment:read', 'application:environment:write',
+    'connections:read',
+]);
+/**
+ * The runtime (data) key a server-side application needs to read and write its state, and
+ * nothing more (docs: public-docs/managed-production.md, "Key types").
+ */
+export const MANAGED_RUNTIME_SCOPES_MINIMAL = Object.freeze([
+    'application:read', 'application:revision:read', 'state:read', 'state:write',
+]);
+/** What a starter's runtime key holds: state plus events, workflows, agents and capabilities. */
+export const MANAGED_RUNTIME_SCOPES_DEFAULT = Object.freeze([
+    ...MANAGED_RUNTIME_SCOPES_MINIMAL, 'events:read', 'workflows:run', 'agents:run', 'capabilities:run',
+]);
+/**
+ * Scopes from the command line: `minimal`, `default`, `control`, or a comma-separated list.
+ * Whether each scope may be granted is the account service's decision; it never issues a
+ * scope the signed-in person does not hold.
+ */
+export function resolveManagedScopes(value) {
+    const presets = { minimal: MANAGED_RUNTIME_SCOPES_MINIMAL, default: MANAGED_RUNTIME_SCOPES_DEFAULT, control: MANAGED_CONTROL_SCOPES };
+    const scopes = presets[value.trim()] ?? value.split(',').map(scope => scope.trim()).filter(Boolean);
+    if (!scopes.length)
+        throw new Error('Name at least one scope: minimal, default, control, or a comma-separated list');
+    for (const scope of scopes) {
+        if (scope === '*' || !/^[a-z][a-z_-]*(?::[a-z_-]+)+$/.test(scope))
+            throw new Error(`"${scope}" is not a scope (expected e.g. state:read). Wildcard keys are operator keys and never belong to an application.`);
+    }
+    return [...new Set(scopes)];
+}
 function loadEnvironment(file) {
     const values = {};
     for (const raw of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
@@ -21,9 +55,8 @@ async function responseJson(response, fallback) {
         throw new Error(String(body.error || body.message || fallback));
     return body;
 }
-export async function configureManagedAccount(options) {
+export async function signInManagedAccount(options) {
     const accountUrl = (options.accountUrl || process.env.FELTDB_MANAGED_ACCOUNT_URL || 'https://feltdb.com').replace(/\/$/, '');
-    const apiUrl = (options.apiUrl || process.env.FELTDB_MANAGED_URL || 'https://api.feltdb.com').replace(/\/$/, '');
     const request = options.fetchImpl || fetch;
     const authenticated = await request(`${accountUrl}/api/auth`, {
         method: 'POST', headers: { 'Content-Type': 'application/json' },
@@ -33,11 +66,37 @@ export async function configureManagedAccount(options) {
     // fetch follows the feltdb.com -> www.feltdb.com redirect. Reuse the final
     // origin so Node does not strip the explicit Cookie header on later
     // cross-origin redirects.
-    const sessionOrigin = authenticated.url ? new URL(authenticated.url).origin : accountUrl;
+    const origin = authenticated.url ? new URL(authenticated.url).origin : accountUrl;
     const cookie = authenticated.headers.get('set-cookie')?.split(';', 1)[0];
     if (!cookie)
         throw new Error('Managed account service did not return a secure session');
-    const headers = { Cookie: cookie, 'Content-Type': 'application/json' };
+    return { origin, headers: { Cookie: cookie, 'Content-Type': 'application/json' }, request };
+}
+/** Mint a key bound to one application. The secret is returned once and never stored here. */
+export async function createManagedKey(session, input) {
+    const created = await responseJson(await session.request(`${session.origin}/api/keys`, {
+        method: 'POST', headers: session.headers,
+        body: JSON.stringify({ id: input.id, namespace: input.namespace, application_id: input.applicationId, scopes: [...input.scopes] }),
+    }), `Could not create the managed key ${input.id}`);
+    if (!created.secret)
+        throw new Error(`Managed key service did not return the credential for ${input.id}`);
+    return { id: String(created.id ?? input.id), secret: String(created.secret), scopes: Array.isArray(created.scopes) ? created.scopes : [...input.scopes] };
+}
+/** Keys of one application: ids, scopes and state, never secrets. */
+export async function listManagedKeys(session, applicationId) {
+    const listed = await responseJson(await session.request(`${session.origin}/api/keys?application_id=${encodeURIComponent(applicationId)}`, { headers: session.headers }), 'Could not list managed keys');
+    return Array.isArray(listed) ? listed : Array.isArray(listed.tokens) ? listed.tokens : [];
+}
+export async function revokeManagedKey(session, keyId) {
+    const response = await session.request(`${session.origin}/api/keys/${encodeURIComponent(keyId)}`, { method: 'DELETE', headers: session.headers });
+    if (!response.ok)
+        await responseJson(response, `Could not revoke the managed key ${keyId}`);
+}
+export async function configureManagedAccount(options) {
+    const apiUrl = (options.apiUrl || process.env.FELTDB_MANAGED_URL || 'https://api.feltdb.com').replace(/\/$/, '');
+    const session = await signInManagedAccount(options);
+    const { request, headers } = session;
+    const sessionOrigin = session.origin;
     const tenants = await responseJson(await request(`${sessionOrigin}/api/tenants`, { headers }), 'Could not load managed workspaces');
     let tenant = Array.isArray(tenants) ? tenants[0] : undefined;
     if (!tenant) {
@@ -58,37 +117,14 @@ export async function configureManagedAccount(options) {
     // Provision through the account origin that issued the human session. The
     // resulting key is still used against apiUrl, but setup must not require a
     // browser session to be trusted by every managed data-plane hostname.
-    const controlKey = await responseJson(await request(`${sessionOrigin}/api/keys`, {
-        method: 'POST', headers,
-        body: JSON.stringify({
-            id: `${options.applicationName}-control`,
-            namespace: application.namespace || options.namespace,
-            application_id: application.id,
-            scopes: [
-                'application:read', 'application:write', 'application:revision:create',
-                'application:revision:read', 'application:revision:promote',
-                'application:environment:read', 'application:environment:write',
-                'connections:read',
-            ],
-        }),
-    }), 'Could not create the managed control-plane key');
-    if (!controlKey.secret)
-        throw new Error('Managed key service did not return the control-plane credential');
-    const dataKey = await responseJson(await request(`${sessionOrigin}/api/keys`, {
-        method: 'POST', headers,
-        body: JSON.stringify({
-            id: `${options.applicationName}-runtime`,
-            namespace: application.namespace || options.namespace,
-            application_id: application.id,
-            scopes: [
-                'application:read', 'application:revision:read',
-                'state:read', 'state:write', 'events:read',
-                'workflows:run', 'agents:run', 'capabilities:run',
-            ],
-        }),
-    }), 'Could not create the managed application data key');
-    if (!dataKey.secret)
-        throw new Error('Managed key service did not return the application data credential');
+    const namespace = application.namespace || options.namespace;
+    const controlKey = await createManagedKey(session, { id: `${options.applicationName}-control`, namespace, applicationId: application.id, scopes: MANAGED_CONTROL_SCOPES })
+        .catch(error => { throw new Error(`Could not create the managed control-plane key: ${error.message}`); });
+    const dataKey = await createManagedKey(session, { id: `${options.applicationName}-runtime`, namespace, applicationId: application.id, scopes: options.runtimeScopes ?? MANAGED_RUNTIME_SCOPES_DEFAULT })
+        .catch(async (error) => {
+        await revokeManagedKey(session, controlKey.id).catch(() => undefined);
+        throw new Error(`Could not create the managed application data key: ${error.message}`);
+    });
     try {
         await responseJson(await request(`${apiUrl}/api/applications/${encodeURIComponent(application.id)}/revisions`, {
             headers: { Authorization: `Bearer ${controlKey.secret}` },
@@ -149,3 +185,25 @@ export async function finalizeManagedProvisioning(options) {
     fs.writeFileSync(managedFile, `${JSON.stringify({ ...managed, revisionId: published.revisionId }, null, 2)}\n`, { mode: 0o600 });
     return { revisionId: published.revisionId };
 }
+/**
+ * Set `name=value` in an env file, creating it with mode 600 or replacing that one line,
+ * and leave the file at mode 600. Used to put a newly minted key where the server process
+ * (or a deploy script) reads it, without the key ever being printed.
+ */
+export function setEnvironmentValue(file, name, value) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name))
+        throw new Error(`${name} is not an environment variable name`);
+    if (/^VITE_|^NEXT_PUBLIC_|^PUBLIC_|^REACT_APP_|^EXPO_PUBLIC_/.test(name))
+        throw new Error(`${name} would be inlined into browser code; a FeltDB key belongs in a server-side variable such as FELTDB_TOKEN`);
+    const lines = fs.existsSync(file) ? fs.readFileSync(file, 'utf8').split(/\r?\n/) : [];
+    const index = lines.findIndex(line => line.startsWith(`${name}=`));
+    if (index >= 0)
+        lines[index] = `${name}=${value}`;
+    else {
+        if (lines.length && lines[lines.length - 1] === '')
+            lines.pop();
+        lines.push(`${name}=${value}`, '');
+    }
+    fs.writeFileSync(file, lines.join('\n'), { mode: 0o600 });
+    fs.chmodSync(file, 0o600);
+}

package/dist/create/package-versions.js

@@ -1,4 +1,4 @@
 // One release train keeps generated applications installable. The repository
 // validation script checks these values against every workspace manifest.
-export const FELTDB_PACKAGE_VERSION = '0.13.0';
+export const FELTDB_PACKAGE_VERSION = '0.16.0';
 export const feltdbPackageRange = `^${FELTDB_PACKAGE_VERSION}`;