@bizagent/dsh 0.0.0-stage → 1.0.0

package/lib/route-guard.js

@@ -0,0 +1,80 @@
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+export function isLoopbackHostname(hostname) {
+    if (hostname === 'localhost' || hostname === '[::1]')
+        return true;
+    const parts = hostname.split('.');
+    return parts.length === 4 && parts[0] === '127'
+        && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+/** Return why a request must be rejected, or undefined when it may reach the handler. */
+export function localRouteRejection(request) {
+    const host = singleHeader(request.headers.host);
+    const hostUrl = host === undefined ? undefined : parseAuthority(host);
+    if (hostUrl === undefined || !isLoopbackHostname(hostUrl.hostname))
+        return 'untrusted-host';
+    if (singleHeader(request.headers['sec-fetch-site'])?.toLowerCase() === 'cross-site') {
+        return 'cross-site-request';
+    }
+    const origin = singleHeader(request.headers.origin);
+    if (origin === undefined) {
+        return SAFE_METHODS.has((request.method ?? 'GET').toUpperCase()) ? undefined : 'origin-rejected';
+    }
+    try {
+        const originUrl = new URL(origin);
+        if (originUrl.protocol !== 'http:' && originUrl.protocol !== 'https:')
+            return 'origin-rejected';
+        return originUrl.host === hostUrl.host ? undefined : 'origin-rejected';
+    }
+    catch {
+        return 'origin-rejected';
+    }
+}
+/** Wrap a route handler so untrusted browser requests get a 403 before any handler code runs. */
+export function guardLocalRoute(handler) {
+    return async (request, response) => {
+        if (rejectUntrustedRequest(request, response))
+            return;
+        await handler(request, response);
+    };
+}
+/** Write the standard 403 response and return true when the request fails the fence. */
+export function rejectUntrustedRequest(request, response) {
+    const rejection = localRouteRejection(request);
+    if (rejection === undefined)
+        return false;
+    response.setHeader('Cache-Control', 'no-store');
+    response.setHeader('Content-Type', 'application/json; charset=utf-8');
+    response.setHeader('X-Content-Type-Options', 'nosniff');
+    response.statusCode = 403;
+    response.end(JSON.stringify({ error: { code: rejection, message: REJECTION_MESSAGES[rejection] } }));
+    return true;
+}
+const REJECTION_MESSAGES = {
+    'untrusted-host': 'This endpoint only serves the local loopback DSH origin.',
+    'cross-site-request': 'Cross-site requests are not accepted.',
+    'origin-rejected': 'Mutation requests must come from this DSH origin.',
+};
+function singleHeader(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+/** Parse a bare `host[:port]` authority; anything with userinfo, a path, query, or fragment is refused. */
+function parseAuthority(authority) {
+    if (authority.length === 0 || /[\s/?#@\\]/u.test(authority))
+        return undefined;
+    try {
+        const url = new URL(`http://${authority}`);
+        return url.username === '' && url.password === '' && url.pathname === '/' ? url : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * DSH's browser login, looked up per request. DSH 0.2 Web provides it as the `connection`
+ * service; hosts without it get only the loopback fence above.
+ */
+export function dshOperatorAuthentication(ctx) {
+    const candidate = ctx.get('connection');
+    return typeof candidate?.requestRejection === 'function' ? candidate : undefined;
+}
+//# sourceMappingURL=route-guard.js.map

package/lib/safe-file.d.ts

@@ -0,0 +1,24 @@
+export interface RegularFileIdentity {
+    dev: number;
+    ino: number;
+}
+export interface ReadRegularFileOptions {
+    /** Reject files larger than this many bytes, checked on the open handle. */
+    maxBytes?: number;
+    /** Require the opened file to be this exact inode, e.g. one validated by an earlier path check. */
+    expected?: RegularFileIdentity;
+}
+/**
+ * Read one file without following a final symlink and without a check-then-read race: the file
+ * is opened with O_NOFOLLOW (O_NONBLOCK keeps a FIFO from blocking the open), then the open
+ * handle is checked to be a regular file and read. Platforms without O_NOFOLLOW fall back to an
+ * lstat check plus the same handle checks.
+ */
+export declare function readRegularFileNoFollow(path: string, options?: ReadRegularFileOptions): Promise<Buffer>;
+/**
+ * Replace a file so that a crash or power loss leaves either the old or the new contents, never an
+ * empty file: write a private temporary file, fsync it, rename it over the target, then fsync the
+ * directory so the rename itself is durable (best effort where directories cannot be fsynced).
+ */
+export declare function writeFileDurably(path: string, contents: string | Uint8Array): Promise<void>;
+//# sourceMappingURL=safe-file.d.ts.map

package/lib/safe-file.js

@@ -0,0 +1,93 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/**
+ * Read one file without following a final symlink and without a check-then-read race: the file
+ * is opened with O_NOFOLLOW (O_NONBLOCK keeps a FIFO from blocking the open), then the open
+ * handle is checked to be a regular file and read. Platforms without O_NOFOLLOW fall back to an
+ * lstat check plus the same handle checks.
+ */
+export async function readRegularFileNoFollow(path, options = {}) {
+    if (constants.O_NOFOLLOW === undefined) {
+        const info = await lstat(path);
+        if (info.isSymbolicLink())
+            throw new Error(`refusing to follow a symlink: ${path}`);
+    }
+    const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+    let handle;
+    try {
+        handle = await open(path, flags);
+    }
+    catch (error) {
+        if (isErrno(error, 'ELOOP'))
+            throw new Error(`refusing to follow a symlink: ${path}`, { cause: error });
+        throw error;
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile())
+            throw new Error(`not a regular file: ${path}`);
+        if (options.expected !== undefined
+            && (info.dev !== options.expected.dev || info.ino !== options.expected.ino)) {
+            throw new Error(`file changed while it was being opened: ${path}`);
+        }
+        if (options.maxBytes !== undefined && info.size > options.maxBytes) {
+            throw new Error(`file exceeds ${options.maxBytes} bytes: ${path}`);
+        }
+        const bytes = await handle.readFile();
+        if (options.maxBytes !== undefined && bytes.length > options.maxBytes) {
+            throw new Error(`file exceeds ${options.maxBytes} bytes: ${path}`);
+        }
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+function isErrno(error, code) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}
+/**
+ * Replace a file so that a crash or power loss leaves either the old or the new contents, never an
+ * empty file: write a private temporary file, fsync it, rename it over the target, then fsync the
+ * directory so the rename itself is durable (best effort where directories cannot be fsynced).
+ */
+export async function writeFileDurably(path, contents) {
+    const directory = dirname(path);
+    await mkdir(directory, { recursive: true });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(contents);
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    await handle.close();
+    try {
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    await syncDirectory(directory);
+}
+async function syncDirectory(directory) {
+    let handle;
+    try {
+        handle = await open(directory, constants.O_RDONLY);
+        await handle.sync();
+    }
+    catch {
+        // Some platforms and filesystems cannot fsync a directory; the file itself is already synced.
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=safe-file.js.map

package/lib/sample-organization.d.ts

@@ -0,0 +1,10 @@
+import type { CreateOrganizationInput } from './home-store.js';
+/** A small growth team with real data to work on, so every BizAgent loop can be tried in minutes. */
+export declare const SAMPLE_ORGANIZATION: Omit<CreateOrganizationInput, 'owner'>;
+/** Files placed in sample Home directories. Existing files are never overwritten. */
+export declare const SAMPLE_FILES: ReadonlyArray<{
+    home: string;
+    path: string;
+    content: string;
+}>;
+//# sourceMappingURL=sample-organization.d.ts.map

package/lib/sample-organization.js

@@ -0,0 +1,46 @@
+import { BIZAGENT_SAMPLE_ORGANIZATION_ID } from './ui-contract.js';
+/** A small growth team with real data to work on, so every BizAgent loop can be tried in minutes. */
+export const SAMPLE_ORGANIZATION = {
+    id: BIZAGENT_SAMPLE_ORGANIZATION_ID,
+    name: 'Sample Shop',
+    mission: 'grow repeat purchases with numbers everyone on the team can trust.',
+    members: [
+        {
+            id: 'growth-lead',
+            displayName: 'Growth lead',
+            roleId: 'growth',
+            roleName: 'Growth',
+            responsibility: 'Decide where the team spends its effort, run Projects, and sign off on results.',
+        },
+        {
+            id: 'data-analyst',
+            displayName: 'Data analyst',
+            roleId: 'analytics',
+            roleName: 'Analytics',
+            responsibility: 'Own metric definitions and compute numbers from the shop data in your workspace.',
+        },
+    ],
+    capabilities: [{
+            id: 'metrics',
+            displayName: 'Metric definitions',
+            responsibility: 'Keep the agreed definitions of GMV, retention, and other shared metrics.',
+        }],
+};
+/** Files placed in sample Home directories. Existing files are never overwritten. */
+export const SAMPLE_FILES = [
+    {
+        home: 'personal:data-analyst',
+        path: 'orders.csv',
+        content: [
+            'order_id,status,amount',
+            'A1,paid,120.50',
+            'A2,cancelled,80.00',
+            'A3,paid,45.25',
+            'A4,refunded,60.00',
+            'A5,paid,200.00',
+            'A6,shipped,34.75',
+            '',
+        ].join('\n'),
+    },
+];
+//# sourceMappingURL=sample-organization.js.map