@feltdb/core 0.12.2 → 0.13.0

package/dist/workspace/local-development-authority.js

@@ -1,19 +1,91 @@
 import http from 'node:http';
+import { createHash, randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
 import path from 'node:path';
 import { FileJsDb } from '../file-db.js';
 import { FELTDB_CONVERGENCE_COLLECTION, FeltDBProposalService } from '../proposal.js';
 import { IntentService } from '../intent.js';
-const DEVELOPMENT_CONTROL_PLANE_CAPABILITIES = {
+/**
+ * Why the development authority does not serve a part of the control plane.
+ *
+ * `feltdb dev` runs a lightweight authority that holds application state and
+ * the application contract. Everything else the control plane names belongs to
+ * a deployed feltdb-server. Each capability is declared — available or not —
+ * so Studio can tell "not part of this instance" from "unknown to Studio", and
+ * the reason says where the feature does live.
+ */
+const SERVER_ONLY = {
+    data: 'Record inspection, writes, sorting and index management through the control plane are served by feltdb-server. In development, the application writes its own state, and Data shows it.',
+    state: 'Semantic history, diff, conflict classification and reconciliation are served by feltdb-server; the development authority keeps current state only.',
+    operations: 'Operation history, rejections, transaction status and audit are recorded by feltdb-server; the development authority does not record them.',
+    agents: 'Agent principals, sessions, authorization decisions and Durable Work run on feltdb-server. The development authority does not run agents; the agents your application declares are listed under Build › Agents.',
+    replication: 'Replication health is reported by a feltdb-server cluster; the development authority is a single local node.',
+    applications: 'Managing applications is part of a deployed feltdb-server; a development session serves exactly one application.',
+    monitoring: 'Instance metrics come from feltdb-server; the development authority does not export them.',
+    settings: 'Instance settings belong to a deployed feltdb-server; a development session is configured by feltdb.config.json.',
+    developer: 'Developer access is issued by feltdb-server; the development authority is unauthenticated and loopback-only.',
+};
+const SERVED = {
+    'overview.instance': { area: 'overview', title: 'Development authority overview', surface: ['GET /v1/control-plane/overview'] },
+    'data.collections.list': { area: 'data', title: 'List declared collections', surface: ['GET /v1/application/schema'] },
+    'data.schema.inspect': { area: 'data', title: 'Inspect the application schema', surface: ['GET /v1/application/schema'] },
+    'data.records.browse': { area: 'data', title: 'Browse records', surface: ['GET /v1/data/{collection}'] },
+};
+/**
+ * Every capability the feltdb-server control plane declares, in its order,
+ * with the area it belongs to. Held equal to `control_plane.rs` by
+ * `development-authority-capabilities.test.mjs`.
+ */
+const CONTROL_PLANE_IDS = [
+    ['overview.instance', 'overview', 'Instance overview'],
+    ['data.collections.list', 'data', 'List collections'],
+    ['data.records.browse', 'data', 'Browse records'],
+    ['data.records.inspect', 'data', 'Inspect a record'],
+    ['data.records.create', 'data', 'Create records'],
+    ['data.records.update', 'data', 'Update records'],
+    ['data.records.delete', 'data', 'Delete records'],
+    ['data.records.sort', 'data', 'Sort records'],
+    ['data.schema.inspect', 'data', 'Inspect the schema'],
+    ['data.indexes.inspect', 'data', 'Inspect indexes'],
+    ['data.indexes.rebuild', 'data', 'Rebuild indexes'],
+    ['data.records.history', 'state', 'Record history'],
+    ['state.resources.list', 'state', 'List state resources'],
+    ['state.history', 'state', 'State history'],
+    ['state.diff.semantic', 'state', 'Semantic diff'],
+    ['state.conflict.classify', 'state', 'Classify conflicts'],
+    ['state.reconciliation.plan', 'state', 'Plan reconciliation'],
+    ['state.reconciliation.execute', 'state', 'Execute reconciliation'],
+    ['state.branch.heads', 'state', 'Branch heads'],
+    ['provenance.record', 'state', 'Record provenance'],
+    ['provenance.transactions', 'operations', 'Recent attributed transactions'],
+    ['agents.list', 'agents', 'List agents'],
+    ['agents.identity', 'agents', 'Agent identity'],
+    ['agents.register', 'agents', 'Register agents'],
+    ['agents.work', 'agents', 'Agent work (Durable Work)'],
+    ['agents.work.review_gate', 'agents', 'Agent work review gate'],
+    ['agents.sessions', 'agents', 'Agent sessions'],
+    ['agents.authorization_decisions', 'agents', 'Agent authorization decisions'],
+    ['agents.task_context', 'agents', 'Agent task context'],
+    ['operations.recent', 'operations', 'Recent operations'],
+    ['operations.rejections', 'operations', 'Rejected operations'],
+    ['operations.events', 'operations', 'Operation events'],
+    ['operations.transaction_status', 'operations', 'Transaction status'],
+    ['operations.correlation_id', 'operations', 'Correlation ids'],
+    ['operations.audit_log', 'operations', 'Audit log'],
+    ['replication.health', 'replication', 'Replication health'],
+    ['applications.list', 'applications', 'List applications'],
+    ['monitoring.metrics', 'monitoring', 'Instance metrics'],
+    ['monitoring.latency', 'monitoring', 'Latency'],
+    ['settings.instance', 'settings', 'Instance settings'],
+    ['settings.mutate', 'settings', 'Change settings'],
+    ['developer.tool_projection', 'developer', 'Tool projection'],
+    ['developer.access', 'developer', 'Developer access'],
+];
+export const DEVELOPMENT_CONTROL_PLANE_CAPABILITIES = {
     contract: 'feltdb.control-plane.capabilities',
     version: 1,
-    capabilities: [
-        { id: 'overview.instance', area: 'overview', title: 'Development authority overview', status: 'available', surface: ['GET /v1/control-plane/overview'], note: '' },
-        { id: 'data.collections.list', area: 'data', title: 'List declared collections', status: 'available', surface: ['GET /v1/application/schema'], note: '' },
-        { id: 'data.schema.inspect', area: 'data', title: 'Inspect the application schema', status: 'available', surface: ['GET /v1/application/schema'], note: '' },
-        { id: 'data.records.browse', area: 'data', title: 'Browse records', status: 'available', surface: ['GET /v1/data/{collection}'], note: '' },
-        { id: 'provenance.transactions', area: 'operations', title: 'Recent attributed transactions', status: 'unsupported', surface: [], note: 'Transaction observability is not available from the lightweight development authority.' },
-        { id: 'replication.health', area: 'replication', title: 'Replication health', status: 'unsupported', surface: [], note: 'Replication health is not available from the lightweight development authority.' },
-    ],
+    capabilities: CONTROL_PLANE_IDS.map(([id, area, title]) => SERVED[id]
+        ? { id, ...SERVED[id], status: 'available', note: '' }
+        : { id, area, title, status: 'unsupported', surface: [], note: SERVER_ONLY[area] }),
 };
 /** Start the durable, unauthenticated loopback authority used by `feltdb dev`. */
 export async function startLocalDevelopmentAuthority(options) {
@@ -37,9 +109,26 @@ export async function startLocalDevelopmentAuthority(options) {
     const proposalService = options.proposalContext ? new FeltDBProposalService(store, options.proposalContext, proposalAuthorityToken) : undefined;
     const intentService = proposalService && options.proposalContext ? new IntentService(store, options.proposalContext, proposalService, options.intentObservations) : undefined;
     const streams = new Set();
+    const notify = (collection) => {
+        // `resource` is the field every client reads (the event contract
+        // feltdb-server serves); `change` is kept for readers of the older frame.
+        const frame = `data: ${JSON.stringify({ resource: collection, change: { capability: collection } })}\n\n`;
+        for (const stream of streams)
+            stream.write(frame);
+    };
     let endpoint = '';
     const server = http.createServer(async (request, response) => {
         try {
+            // The authority is unauthenticated, so which pages may reach it is the
+            // whole boundary: only a loopback origin (the developer's own application
+            // and Studio) and a loopback Host (not a rebound DNS name). A request
+            // without an Origin is not a browser page and is not restricted here.
+            if (!loopbackHost(request.headers.host) || (request.headers.origin !== undefined && !loopbackOrigin(request.headers.origin))) {
+                response.statusCode = 403;
+                response.setHeader('Content-Type', 'application/json');
+                response.end(JSON.stringify({ error: 'NON_LOOPBACK_ORIGIN', message: 'The development authority serves loopback origins only.' }));
+                return;
+            }
             response.setHeader('Access-Control-Allow-Origin', '*');
             response.setHeader('Access-Control-Allow-Methods', 'GET, POST, PATCH, DELETE, OPTIONS');
             response.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, FeltDB-Protocol, FeltDB-Proposal-Authority');
@@ -349,14 +438,106 @@ export async function startLocalDevelopmentAuthority(options) {
                 json(response, 405, { error: 'METHOD_NOT_ALLOWED' });
                 return;
             }
+            const authMatch = pathname.match(/^\/v1\/auth\/(signup|signin|signout|session)$/);
+            if (authMatch) {
+                const operation = authMatch[1];
+                const expectedMethod = operation === 'session' ? 'GET' : 'POST';
+                if (request.method !== expectedMethod) {
+                    json(response, 405, { error: 'METHOD_NOT_ALLOWED' });
+                    return;
+                }
+                const body = operation === 'signup' || operation === 'signin' ? parseObject(await readBody(request)) : {};
+                const bearer = String(request.headers.authorization || '').replace(/^Bearer\s+/i, '');
+                const outcome = developmentAuth(db, operation, body, bearer);
+                json(response, outcome.status, outcome.body);
+                return;
+            }
+            // The direct data plane `HttpJsDb` speaks to any authority, so an
+            // application connected to this one behaves as it would against
+            // feltdb-server: same routes, same shapes, same refusals.
+            if (request.method === 'GET' && pathname === '/revision') {
+                json(response, 200, { revision: db.get_sequence(), scope: db.instance_id() });
+                return;
+            }
+            if (request.method === 'POST' && pathname === '/query') {
+                const query = parseObject(await readBody(request));
+                if (namesPrivateCollection([query.collection])) {
+                    refusePrivate(response);
+                    return;
+                }
+                try {
+                    json(response, 200, await db.authority_query(query));
+                }
+                catch (error) {
+                    const code = error.code;
+                    json(response, 400, { code, error: errorMessage(error), message: errorMessage(error) });
+                }
+                return;
+            }
+            if (request.method === 'POST' && pathname === '/transactions/read-basis') {
+                const reads = parseObject(await readBody(request));
+                if (namesPrivateCollection(readSetCollections(reads))) {
+                    refusePrivate(response);
+                    return;
+                }
+                json(response, 200, await db.read_basis(reads));
+                return;
+            }
+            if (request.method === 'POST' && pathname === '/transactions') {
+                const transaction = parseObject(await readBody(request));
+                if (namesPrivateCollection([
+                    ...(transaction.operations ?? []).map((operation) => operation?.collection),
+                    ...(transaction.preconditions ?? []).map((condition) => condition?.collection),
+                    ...(transaction.fences ?? []).flatMap((fence) => readSetCollections(fence?.reads)),
+                ])) {
+                    refusePrivate(response);
+                    return;
+                }
+                let result;
+                try {
+                    result = await db.commit_transaction(transaction);
+                }
+                catch (error) {
+                    json(response, transactionRefusalStatus(error), transactionRefusal(error));
+                    return;
+                }
+                json(response, 200, { ...result, status: 'committed' });
+                if (!result.duplicate) {
+                    const collections = new Set((transaction.operations ?? []).map((operation) => operation.collection));
+                    for (const collection of collections)
+                        notify(collection);
+                }
+                return;
+            }
+            const casMatch = pathname.match(/^\/collections\/([^/]+)\/([^/]+)\/cas$/);
+            if (request.method === 'POST' && casMatch) {
+                const collection = decodeURIComponent(casMatch[1]);
+                if (namesPrivateCollection([collection])) {
+                    refusePrivate(response);
+                    return;
+                }
+                const input = parseObject(await readBody(request));
+                const result = await db.cas({
+                    key: `${collection}:${decodeURIComponent(casMatch[2])}`,
+                    expectedVersion: Number(input.expectedVersion),
+                    expectedEpoch: input.expectedEpoch,
+                    expectedLeaseId: input.expectedLeaseId,
+                    rejectIfDiverged: input.rejectIfDiverged,
+                    value: JSON.stringify(input.value ?? {}),
+                });
+                json(response, 200, result);
+                if (result.updated)
+                    notify(collection);
+                return;
+            }
             const match = pathname.match(/^\/collections\/([^/]+)(?:\/([^/]+))?$/);
             if (!match) {
                 json(response, 404, { error: 'NOT_FOUND' });
                 return;
             }
             const collection = decodeURIComponent(match[1]);
-            if (collection.startsWith('_feltdb.')) {
-                json(response, 403, { error: 'SYSTEM_COLLECTION_REQUIRES_SERVICE_API' });
+            if (namesPrivateCollection([collection])) {
+                refusePrivate(response);
                 return;
             }
             const id = match[2] ? decodeURIComponent(match[2]) : undefined;
@@ -406,9 +587,7 @@ export async function startLocalDevelopmentAuthority(options) {
                 return;
             }
             json(response, request.method === 'POST' ? 201 : 200, { ok: true });
-            const frame = `data: ${JSON.stringify({ change: { capability: collection } })}\n\n`;
-            for (const stream of streams)
-                stream.write(frame);
+            notify(collection);
         }
         catch (error) {
             if (!response.headersSent)
@@ -440,11 +619,152 @@ function json(response, status, value) {
     response.setHeader('Content-Type', 'application/json; charset=utf-8');
     response.end(JSON.stringify(value));
 }
+const IDENTITIES = '_feltdb.development_identities';
+const SESSIONS = '_feltdb.development_sessions';
+const SESSION_TTL_MS = 15 * 60_000;
+function developmentAuth(db, operation, body, bearer) {
+    const read = (key) => {
+        const result = db.get(key);
+        if (!result.success)
+            throw new Error(result.error);
+        return result.data ? JSON.parse(result.data) : undefined;
+    };
+    const tokenHash = (token) => createHash('sha256').update(token).digest('hex');
+    const passwordHash = (password, salt) => scryptSync(password, salt, 32).toString('hex');
+    const refuse = (status, code, message) => ({ status, body: { code, error: code, message } });
+    const issue = (identity) => {
+        const token = randomBytes(32).toString('hex');
+        const session = { session_id: `session_${randomBytes(12).toString('hex')}`, expires_at: Date.now() + SESSION_TTL_MS };
+        const stored = db.insert(`${SESSIONS}:${tokenHash(token)}`, JSON.stringify({ ...session, user_id: identity.id }));
+        if (!stored.success)
+            throw new Error(stored.error);
+        return { status: 200, body: { access_token: token, actor: { user_id: identity.id, email: identity.email, display_name: identity.display_name }, session } };
+    };
+    if (operation === 'signout') {
+        if (bearer)
+            db.delete(`${SESSIONS}:${tokenHash(bearer)}`);
+        return { status: 200, body: {} };
+    }
+    if (operation === 'session') {
+        const sessionKey = `${SESSIONS}:${tokenHash(bearer)}`;
+        const session = bearer ? read(sessionKey) : undefined;
+        // An expired session is dead; remove it rather than keep it forever.
+        if (session && session.expires_at <= Date.now())
+            db.delete(sessionKey);
+        const identity = session && session.expires_at > Date.now()
+            ? read(`${IDENTITIES}:${session.user_id}`)
+            : undefined;
+        if (!session || !identity)
+            return refuse(401, 'AUTHENTICATION_REQUIRED', 'Authentication required');
+        return { status: 200, body: { access_token: bearer, actor: { user_id: identity.id, email: identity.email, display_name: identity.display_name }, session: { session_id: session.session_id, expires_at: session.expires_at } } };
+    }
+    const email = String(body.email ?? '').trim().toLowerCase();
+    const password = String(body.password ?? '');
+    if (!email || password.length < 8)
+        return refuse(422, 'INVALID_CREDENTIALS_FORMAT', 'email and a password of at least 8 characters are required');
+    const byEmail = `${IDENTITIES}:email:${createHash('sha256').update(email).digest('hex')}`;
+    const existingId = read(byEmail)?.id;
+    if (operation === 'signup') {
+        if (existingId)
+            return refuse(409, 'CONFLICT', 'identity already exists');
+        const salt = randomBytes(16).toString('hex');
+        const identity = { id: `user_${randomBytes(12).toString('hex')}`, email, display_name: typeof body.display_name === 'string' ? body.display_name : undefined, salt, password_hash: passwordHash(password, salt), created_at: new Date().toISOString() };
+        const claimed = db.insert(byEmail, JSON.stringify({ id: identity.id }));
+        if (!claimed.success)
+            return refuse(409, 'CONFLICT', 'identity already exists');
+        const stored = db.insert(`${IDENTITIES}:${identity.id}`, JSON.stringify(identity));
+        if (!stored.success) {
+            // Do not leave the email claimed by an identity that was never stored.
+            db.delete(byEmail);
+            throw new Error(stored.error);
+        }
+        return issue(identity);
+    }
+    const identity = existingId ? read(`${IDENTITIES}:${existingId}`) : undefined;
+    const presented = Buffer.from(passwordHash(password, identity?.salt ?? 'no-identity'), 'hex');
+    const expected = Buffer.from(identity?.password_hash ?? '0'.repeat(64), 'hex');
+    if (!identity || presented.length !== expected.length || !timingSafeEqual(presented, expected)) {
+        return refuse(401, 'INVALID_CREDENTIALS', 'invalid credentials');
+    }
+    return issue(identity);
+}
+/**
+ * `_feltdb.*` collections are the authority's own records — development
+ * identities and sessions among them — and no client route reads or writes
+ * them: not `/collections`, not a query, not a transaction or its fences.
+ */
+function namesPrivateCollection(collections) {
+    // Coerced the way the transaction and query engines coerce a collection
+    // name, so a value that is not a string (`["_feltdb.x"]` stringifies to the
+    // private name) is judged by what it will be read as, not by its type.
+    return collections.some(collection => collection !== undefined && collection !== null
+        && String(collection).trim().toLowerCase().startsWith('_feltdb.'));
+}
+function loopbackHost(host) {
+    if (!host)
+        return true;
+    try {
+        return LOOPBACK_HOSTNAMES.has(new URL(`http://${host}`).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+function loopbackOrigin(origin) {
+    if (!origin)
+        return false;
+    try {
+        return LOOPBACK_HOSTNAMES.has(new URL(origin).hostname);
+    }
+    catch {
+        return false;
+    }
+}
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]']);
+function readSetCollections(reads) {
+    const set = (reads ?? {});
+    return [...(set.records ?? []), ...(set.predicates ?? [])].map(entry => entry?.collection);
+}
+function refusePrivate(response) {
+    json(response, 403, { error: 'SYSTEM_COLLECTION_REQUIRES_SERVICE_API' });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * A refused transaction, in the document feltdb-server answers with: a lost
+ * conditional race is `409 PRECONDITION_FAILED` with the failed predicate, a
+ * reused transaction id is `409` with its idempotency code, and a malformed
+ * request is `400`. Callers type the refusal from `code`, never from prose.
+ */
+function transactionRefusal(error) {
+    const refusal = error;
+    return {
+        error: errorMessage(error),
+        code: refusal.feltdbCode ?? refusal.code,
+        ...(refusal.feltdbConflict ? { failure: refusal.feltdbConflict } : {}),
+    };
+}
+function transactionRefusalStatus(error) {
+    const refusal = error;
+    if (refusal.feltdbCode === 'PRECONDITION_FAILED')
+        return 409;
+    if (refusal.code === 'IDEMPOTENCY_CONFLICT' || refusal.code === 'IDEMPOTENCY_UNVERIFIABLE')
+        return 409;
+    return 400;
+}
+const MAX_BODY_BYTES = 1024 * 1024;
 function readBody(request) {
     return new Promise((resolve, reject) => {
         let body = '';
         request.setEncoding('utf8');
-        request.on('data', chunk => { body += chunk; });
+        request.on('data', chunk => {
+            body += chunk;
+            if (body.length > MAX_BODY_BYTES) {
+                request.destroy();
+                reject(new Error('Request body is too large'));
+            }
+        });
         request.once('end', () => resolve(body));
         request.once('error', reject);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feltdb/core",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "FeltDB Core - Application-facing database with Browser, Local, and Server runtimes. Durable state, reactive APIs.",
   "license": "MIT",
   "type": "module",