@bizagent/dsh 0.0.0-stage → 1.0.0

package/lib/project-ledger.js

@@ -0,0 +1,189 @@
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
+import { z } from 'zod';
+import { HomeAddressSchema, stableId } from './domain.js';
+const ProjectWorkSnapshotSchema = z.object({
+    id: z.string().min(1),
+    status: z.enum(['completed', 'cancelled']),
+    resultMessageId: z.string().min(1).optional(),
+});
+const ProjectClaimSchema = z.object({
+    id: z.string().min(1),
+    summary: z.string().min(1).max(200),
+    body: z.string().min(1).max(15000),
+    doneWhenAssessment: z.string().min(1).max(4000),
+    work: z.array(ProjectWorkSnapshotSchema),
+    artifacts: z.array(z.object({
+        path: z.string().max(500).refine(path => path.startsWith('artifacts/')
+            && !path.includes('\\') && !path.includes('\0')
+            && path.split('/').every(part => part !== '' && part !== '.' && part !== '..'), 'Project artifact path must be canonical under artifacts/'),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/),
+        bytes: z.number().int().nonnegative().max(8 * 1024 * 1024),
+        snapshot: z.literal(true),
+    })).max(10).optional(),
+    submittedBySessionId: z.string().min(1),
+    submittedAt: z.string().min(1),
+});
+const ProjectReviewSchema = z.object({
+    claimId: z.string().min(1),
+    decision: z.enum(['accept', 'rework']),
+    reason: z.string().min(1).max(4000),
+    reviewedBySessionId: z.string().min(1).optional(),
+    reviewedByPrincipal: z.string().trim().min(1).max(200).optional(),
+    reviewedAt: z.string().min(1),
+}).superRefine((review, context) => {
+    if ((review.reviewedBySessionId === undefined) === (review.reviewedByPrincipal === undefined)) {
+        context.addIssue({ code: 'custom', message: 'Project review needs exactly one Session or human principal' });
+    }
+});
+export const ProjectSeatSchema = z.object({
+    id: z.string().regex(/^seat-[a-f0-9]{20}$/),
+    address: z.string().min(1).max(200),
+    homeAddress: HomeAddressSchema,
+    responsibility: z.string().min(1).max(1000),
+    status: z.enum(['active', 'released']),
+    joinedAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    releasedAt: z.string().datetime().optional(),
+}).superRefine((seat, context) => {
+    if ((seat.status === 'released') !== (seat.releasedAt !== undefined)) {
+        context.addIssue({ code: 'custom', path: ['releasedAt'], message: 'released Seat needs a release time' });
+    }
+});
+const ProjectSeatEventSchema = z.object({
+    seatAddress: z.string().min(1).max(200),
+    homeAddress: HomeAddressSchema,
+    action: z.enum(['joined', 'responsibility-updated', 'released', 'rejoined']),
+    responsibility: z.string().min(1).max(1000),
+    bySessionId: z.string().min(1),
+    at: z.string().datetime(),
+});
+export const FormalProjectSchema = z.object({
+    schemaVersion: z.literal(1),
+    id: z.string().min(1),
+    idempotencyKey: z.string().min(1).max(128),
+    lead: HomeAddressSchema,
+    driver: z.string().regex(/^project:project-[a-f0-9]{20}$/).optional(),
+    createdBySessionId: z.string().min(1),
+    title: z.string().min(1).max(120),
+    goal: z.string().min(1).max(4000),
+    doneWhen: z.string().min(1).max(2000),
+    status: z.enum(['open', 'awaiting_acceptance', 'accepted']),
+    revision: z.number().int().positive(),
+    claims: z.array(ProjectClaimSchema),
+    reviews: z.array(ProjectReviewSchema),
+    seats: z.array(ProjectSeatSchema).max(32).optional(),
+    seatEvents: z.array(ProjectSeatEventSchema).optional(),
+    currentClaimId: z.string().min(1).optional(),
+    acceptedClaimId: z.string().min(1).optional(),
+    createdAt: z.string().min(1),
+    updatedAt: z.string().min(1),
+}).superRefine((project, context) => {
+    if (project.driver !== undefined && project.driver !== `project:${project.id}`) {
+        context.addIssue({ code: 'custom', path: ['driver'], message: 'Project driver must be its own Main address' });
+    }
+    const claimIds = new Set(project.claims.map(claim => claim.id));
+    const reviewedIds = new Set(project.reviews.map(review => review.claimId));
+    const seats = project.seats ?? [];
+    if (new Set(seats.map(seat => seat.homeAddress)).size !== seats.length
+        || new Set(seats.map(seat => seat.address)).size !== seats.length) {
+        context.addIssue({ code: 'custom', path: ['seats'], message: 'Project Seat Home and address must be unique' });
+    }
+    for (const [index, seat] of seats.entries()) {
+        if (seat.id !== stableId('seat', seat.homeAddress)
+            || seat.address !== `seat:${project.id}:${seat.id}`
+            || seat.homeAddress === project.lead || seat.homeAddress.startsWith('personal:')) {
+            context.addIssue({ code: 'custom', path: ['seats', index], message: 'Project Seat identity is invalid' });
+        }
+    }
+    for (const [index, event] of (project.seatEvents ?? []).entries()) {
+        if (!seats.some(seat => seat.address === event.seatAddress && seat.homeAddress === event.homeAddress)) {
+            context.addIssue({ code: 'custom', path: ['seatEvents', index], message: 'Project Seat event has no matching Seat' });
+        }
+    }
+    if (claimIds.size !== project.claims.length) {
+        context.addIssue({ code: 'custom', path: ['claims'], message: 'duplicate Project claim' });
+    }
+    for (const [index, claim] of project.claims.entries()) {
+        const paths = (claim.artifacts ?? []).map(artifact => artifact.path);
+        if (new Set(paths).size !== paths.length) {
+            context.addIssue({ code: 'custom', path: ['claims', index, 'artifacts'], message: 'duplicate Project artifact' });
+        }
+    }
+    if (reviewedIds.size !== project.reviews.length) {
+        context.addIssue({ code: 'custom', path: ['reviews'], message: 'duplicate Project review' });
+    }
+    if (project.revision !== 1 + project.claims.length + project.reviews.length
+        + (project.seatEvents?.length ?? 0)) {
+        context.addIssue({ code: 'custom', path: ['revision'], message: 'Project revision does not match its history' });
+    }
+    if (project.currentClaimId !== undefined && !claimIds.has(project.currentClaimId)) {
+        context.addIssue({ code: 'custom', path: ['currentClaimId'], message: 'current claim is missing' });
+    }
+    if (project.currentClaimId !== project.claims.at(-1)?.id) {
+        context.addIssue({ code: 'custom', path: ['currentClaimId'], message: 'current claim must be the latest version' });
+    }
+    if (project.acceptedClaimId !== undefined && !claimIds.has(project.acceptedClaimId)) {
+        context.addIssue({ code: 'custom', path: ['acceptedClaimId'], message: 'accepted claim is missing' });
+    }
+    if (project.status === 'awaiting_acceptance' && project.currentClaimId === undefined) {
+        context.addIssue({ code: 'custom', path: ['currentClaimId'], message: 'submission is required' });
+    }
+    if (project.status === 'accepted' && project.acceptedClaimId === undefined) {
+        context.addIssue({ code: 'custom', path: ['acceptedClaimId'], message: 'acceptance is required' });
+    }
+    if (project.status === 'accepted' && (project.acceptedClaimId !== project.currentClaimId
+        || project.reviews.at(-1)?.decision !== 'accept'
+        || project.reviews.at(-1)?.claimId !== project.currentClaimId)) {
+        context.addIssue({ code: 'custom', path: ['acceptedClaimId'], message: 'accepted Project requires a review of the current claim' });
+    }
+    if (project.status === 'awaiting_acceptance' && reviewedIds.has(project.currentClaimId ?? '')) {
+        context.addIssue({ code: 'custom', path: ['status'], message: 'pending claim is already reviewed' });
+    }
+    if (project.status === 'open' && project.claims.length > 0
+        && (project.reviews.at(-1)?.decision !== 'rework'
+            || project.reviews.at(-1)?.claimId !== project.currentClaimId)) {
+        context.addIssue({ code: 'custom', path: ['status'], message: 'open Project with a claim requires rework' });
+    }
+    for (const [index, review] of project.reviews.entries()) {
+        if (!claimIds.has(review.claimId)) {
+            context.addIssue({ code: 'custom', path: ['reviews', index], message: 'reviewed claim is missing' });
+        }
+    }
+});
+export const BIZAGENT_PROJECT_DOMAIN = defineDomain({
+    name: 'bizagent_project',
+    version: 0,
+    tables: { projects: domainTable(FormalProjectSchema) },
+});
+export class ProjectLedger {
+    domain;
+    mutationTail = Promise.resolve();
+    constructor(domain) {
+        this.domain = domain;
+    }
+    static async open(facility) {
+        return new ProjectLedger(await facility.open(BIZAGENT_PROJECT_DOMAIN));
+    }
+    async withWrite(update) {
+        const task = this.mutationTail.catch(() => undefined).then(update);
+        this.mutationTail = task;
+        return task;
+    }
+    get(id) {
+        const record = this.domain.table('projects').get(id);
+        return record === undefined ? undefined : FormalProjectSchema.parse(record);
+    }
+    list() {
+        return [...this.domain.table('projects').entries()]
+            .map(([, record]) => FormalProjectSchema.parse(record))
+            .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+    }
+    async put(project) {
+        const parsed = FormalProjectSchema.parse(project);
+        await this.domain.table('projects').put(parsed.id, parsed);
+    }
+    async close() {
+        await this.domain.close();
+    }
+}
+//# sourceMappingURL=project-ledger.js.map

package/lib/project-review-transport.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { FormalProject } from './project-ledger.js';
+import type { BizAgentService } from './service.js';
+export interface ProjectReviewPrincipal {
+    userId: string;
+}
+export interface ProjectReviewRouteOptions {
+    authenticateUser: (request: IncomingMessage) => ProjectReviewPrincipal | null | Promise<ProjectReviewPrincipal | null>;
+    authorizeMutation: (request: IncomingMessage, principal: ProjectReviewPrincipal) => boolean | Promise<boolean>;
+    /** Check the current Project and its lead against this human's actual grant. */
+    authorizeReview: (principal: ProjectReviewPrincipal, project: Readonly<FormalProject>) => boolean | Promise<boolean>;
+}
+/** Optional human Project acceptance route; Agent reviews continue through their bound Sessions. */
+export declare function createProjectReviewHttpHandler(service: BizAgentService, options: ProjectReviewRouteOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** Mount on the local DSH web server behind the loopback Host / same-origin route guard. */
+export declare function registerProjectReviewRoute(webServer: {
+    register: (route: {
+        kind: 'exact';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    }) => () => void;
+}, service: BizAgentService, options: ProjectReviewRouteOptions): () => void;
+//# sourceMappingURL=project-review-transport.d.ts.map

package/lib/project-review-transport.js

@@ -0,0 +1,155 @@
+import { z } from 'zod';
+import { stableId } from './domain.js';
+import { guardLocalRoute } from './route-guard.js';
+import { BIZAGENT_PROJECT_REVIEW_API } from './ui-contract.js';
+import { ProjectSnapshotStore, WorkSnapshotStore } from './worklog-snapshot.js';
+const MAX_BODY_BYTES = 8 * 1024;
+const Id = z.string().trim().min(1).max(200);
+const Review = z.strictObject({ projectId: Id, claimId: Id,
+    expectedRevision: z.number().int().positive(),
+    decision: z.enum(['accept', 'rework']), reason: z.string().trim().min(1).max(4000) });
+/** Optional human Project acceptance route; Agent reviews continue through their bound Sessions. */
+export function createProjectReviewHttpHandler(service, options) {
+    return async (req, res) => {
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        if (req.method !== 'GET' && req.method !== 'POST') {
+            res.setHeader('Allow', 'GET, POST');
+            reply(res, 405, failure('method-not-allowed', 'Use GET or POST for Project review.'));
+            return;
+        }
+        try {
+            const principal = await options.authenticateUser(req);
+            if (!principal?.userId.trim()) {
+                reply(res, 401, failure('authentication-required', 'Sign in to review a Project.'));
+                return;
+            }
+            if (req.method === 'GET') {
+                const query = new URL(req.url ?? '', 'http://bizagent.local').searchParams;
+                if (query.get('inbox') === '1') {
+                    const offset = z.string().regex(/^(0|[1-9][0-9]{0,5})$/)
+                        .transform(Number).parse(query.get('offset') ?? '0');
+                    reply(res, 200, await service.listPendingProjectOutcomeReviewsAsHuman(principal.userId, (_actor, current) => options.authorizeReview(principal, current), offset));
+                    return;
+                }
+                const projectId = Id.parse(query.get('projectId'));
+                const project = service.projectLedger?.get(projectId);
+                if (!project || !await options.authorizeReview(principal, project)) {
+                    reply(res, 403, failure('review-forbidden', 'This Project cannot be reviewed here.'));
+                    return;
+                }
+                if (query.has('artifactPath')) {
+                    const claimId = Id.parse(query.get('claimId'));
+                    const artifactPath = z.string().min(1).max(500).parse(query.get('artifactPath'));
+                    if (query.has('workId')) {
+                        const workId = Id.parse(query.get('workId'));
+                        const claim = project.status === 'awaiting_acceptance'
+                            && project.currentClaimId === claimId
+                            ? project.claims.find(item => item.id === claimId) : undefined;
+                        const reference = claim?.work.find(item => item.id === workId
+                            && item.status === 'completed');
+                        const work = service.workLedger?.get(workId);
+                        const artifact = work?.projectId === project.id && work.status === 'completed'
+                            && work.resultMessageId === reference?.resultMessageId
+                            ? work.resultArtifacts?.find(item => item.path === artifactPath) : undefined;
+                        if (!reference || !artifact || !work) {
+                            reply(res, 404, failure('artifact-unavailable', 'Work artifact is unavailable.'));
+                            return;
+                        }
+                        const bytes = await new WorkSnapshotStore(service.store.rootFor(work.assignee))
+                            .read(artifact.sha256, artifact.bytes);
+                        res.setHeader('Content-Type', 'application/octet-stream');
+                        res.setHeader('Content-Disposition', 'attachment; filename="work-artifact"');
+                        res.setHeader('Content-Length', bytes.byteLength);
+                        res.end(bytes);
+                        return;
+                    }
+                    const artifact = project.claims.find(item => item.id === claimId)?.artifacts
+                        ?.find(item => item.path === artifactPath);
+                    if (!artifact) {
+                        reply(res, 404, failure('artifact-unavailable', 'Project artifact is unavailable.'));
+                        return;
+                    }
+                    const bytes = await new ProjectSnapshotStore(service.store.rootFor(project.lead))
+                        .read(artifact.sha256, artifact.bytes);
+                    res.setHeader('Content-Type', 'application/octet-stream');
+                    res.setHeader('Content-Disposition', 'attachment; filename="project-artifact"');
+                    res.setHeader('Content-Length', bytes.byteLength);
+                    res.end(bytes);
+                    return;
+                }
+                const latestReview = project.reviews?.at(-1);
+                const reworkId = latestReview?.decision === 'rework'
+                    && latestReview.claimId === project.currentClaimId
+                    ? stableId('project-outcome-rework', `${project.id}:${latestReview.claimId}`) : undefined;
+                reply(res, 200, { canReview: project.status === 'awaiting_acceptance',
+                    revision: project.revision, claimId: project.currentClaimId ?? null,
+                    ...(reworkId === undefined ? {} : { outcomeReworkNotification: {
+                            claimId: latestReview.claimId,
+                            state: service.ledger.getInboxMessage(reworkId)
+                                && service.ledger.getInboxDelivery(reworkId, project.lead)?.status === 'delivered'
+                                ? 'delivered' : 'pending',
+                        } }) });
+                return;
+            }
+            if (!await options.authorizeMutation(req, principal)) {
+                reply(res, 403, failure('mutation-forbidden', 'This request cannot review a Project.'));
+                return;
+            }
+            if (!String(req.headers['content-type'] ?? '').toLowerCase().startsWith('application/json')) {
+                reply(res, 415, failure('content-type', 'Send JSON to review a Project.'));
+                return;
+            }
+            const input = Review.parse(await readJson(req));
+            const result = await service.reviewProjectAsHuman(principal.userId, input, (_actor, current) => options.authorizeReview(principal, current));
+            reply(res, 200, result);
+        }
+        catch (error) {
+            if (error instanceof z.ZodError || error instanceof RequestError) {
+                reply(res, 400, failure('invalid-request', 'Check the Project review fields.'));
+            }
+            else if (error instanceof Error && error.message.includes('not authorized')) {
+                reply(res, 403, failure('review-forbidden', 'This Project cannot be reviewed here.'));
+            }
+            else if (error instanceof Error && error.message.includes('revision conflict')) {
+                reply(res, 409, failure('revision-conflict', 'Project changed. Refresh before reviewing.'));
+            }
+            else {
+                reply(res, 409, failure('review-rejected', 'Project review could not be completed. Refresh and check its current state.'));
+            }
+        }
+    };
+}
+/** Mount on the local DSH web server behind the loopback Host / same-origin route guard. */
+export function registerProjectReviewRoute(webServer, service, options) {
+    return webServer.register({ kind: 'exact', path: BIZAGENT_PROJECT_REVIEW_API,
+        handler: guardLocalRoute(createProjectReviewHttpHandler(service, options)) });
+}
+class RequestError extends Error {
+}
+async function readJson(req) {
+    let total = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += bytes.length;
+        if (total > MAX_BODY_BYTES)
+            throw new RequestError('request body too large');
+        chunks.push(bytes);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new RequestError('invalid JSON');
+    }
+}
+function failure(code, message) {
+    return { error: { code, message } };
+}
+function reply(res, status, body) {
+    res.statusCode = status;
+    res.end(JSON.stringify(body));
+}
+//# sourceMappingURL=project-review-transport.js.map

package/lib/project-seat-context.d.ts

@@ -0,0 +1,18 @@
+import type { HomeAddress, ProjectSeatAddress } from './domain.js';
+import type { FormalProject, ProjectSeat } from './project-ledger.js';
+export interface ProjectSeatContext {
+    projectId: string;
+    projectRevision: number;
+    title: string;
+    goal: string;
+    doneWhen: string;
+    status: FormalProject['status'];
+    lead: HomeAddress;
+    seatAddress: ProjectSeatAddress;
+    homeAddress: HomeAddress;
+    responsibility: string;
+}
+export declare function projectSeatContext(project: FormalProject, seat: ProjectSeat): ProjectSeatContext;
+/** Situates a Home-bound Session in one Seat without claiming a separate execution identity. */
+export declare function renderProjectSeatContext(context: ProjectSeatContext): string;
+//# sourceMappingURL=project-seat-context.d.ts.map

package/lib/project-seat-context.js

@@ -0,0 +1,34 @@
+import { inlineText, untrustedBlock } from './untrusted-text.js';
+export function projectSeatContext(project, seat) {
+    return {
+        projectId: project.id, projectRevision: project.revision,
+        title: project.title, goal: project.goal, doneWhen: project.doneWhen,
+        status: project.status,
+        lead: project.lead, seatAddress: seat.address,
+        homeAddress: seat.homeAddress, responsibility: seat.responsibility,
+    };
+}
+/** Situates a Home-bound Session in one Seat without claiming a separate execution identity. */
+export function renderProjectSeatContext(context) {
+    return [
+        '# Project Seat context',
+        `Project ID: ${inlineText(context.projectId)}`,
+        `Project revision: ${context.projectRevision}`,
+        `Project status: ${inlineText(context.status)}`,
+        `Project title: ${inlineText(context.title)}`,
+        `Project lead: ${inlineText(context.lead)}`,
+        `Your Seat address: ${inlineText(context.seatAddress)}`,
+        `Your execution Home: ${inlineText(context.homeAddress)}`,
+        '',
+        untrustedBlock('Your responsibility', context.responsibility),
+        '',
+        untrustedBlock('Project goal', context.goal),
+        '',
+        untrustedBlock('Done when', context.doneWhen),
+        '',
+        'This Session uses the execution Home above. The Seat address routes and attributes Project messages; it does not change tool authority.',
+        'Read the current Project with bizagent_project_read before relying on its Work or artifacts. The revision above may become stale.',
+        'For a Project reply, use bizagent_inbox_send with reply_to. A new Project message needs project_id. An ordinary reply does not complete formal Work.',
+    ].join('\n');
+}
+//# sourceMappingURL=project-seat-context.js.map

package/lib/proposal-review-transport.d.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type MemoryProposal } from './domain.js';
+import type { BizAgentService } from './service.js';
+export declare const BIZAGENT_PROPOSAL_REVIEW_API = "/api/bizagent/v1/proposals/decision";
+export interface ProposalReviewPrincipal {
+    userId: string;
+}
+export interface ProposalReviewRouteOptions {
+    /** Resolve identity from a host-verified human session, never from the request body. */
+    authenticateHuman(request: IncomingMessage): ProposalReviewPrincipal | null | Promise<ProposalReviewPrincipal | null>;
+    /** Enforce host CSRF protection or a non-cookie credential. */
+    authorizeMutation(request: IncomingMessage, principal: ProposalReviewPrincipal): boolean | Promise<boolean>;
+    /** Check this proposal, action, and target Home; return a durable authority reference on success. */
+    authorizeProposal(request: IncomingMessage, principal: ProposalReviewPrincipal, proposal: MemoryProposal, action: 'accept' | 'reject'): string | null | Promise<string | null>;
+}
+/** Register explicitly in an authenticated host; the local alpha UI does not install this route. */
+export declare function createProposalReviewHttpHandler(service: BizAgentService, options: ProposalReviewRouteOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** Mount on the local DSH web server behind the loopback Host / same-origin route guard. */
+export declare function registerProposalReviewRoute(webServer: {
+    register: (route: {
+        kind: 'exact';
+        path: string;
+        handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    }) => () => void;
+}, service: BizAgentService, options: ProposalReviewRouteOptions): () => void;
+//# sourceMappingURL=proposal-review-transport.d.ts.map

package/lib/proposal-review-transport.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { parseHomeAddress } from './domain.js';
+import { guardLocalRoute } from './route-guard.js';
+import { BizAgentUiFacade } from './ui-host.js';
+import { BIZAGENT_UI_API } from './ui-contract.js';
+export const BIZAGENT_PROPOSAL_REVIEW_API = `${BIZAGENT_UI_API}/proposals/decision`;
+const Decision = z.strictObject({
+    ownerAddress: z.string().min(3).max(200),
+    proposalId: z.string().min(1).max(200),
+    action: z.enum(['accept', 'reject']),
+    decision: z.string().trim().min(1).max(4000),
+});
+/** Register explicitly in an authenticated host; the local alpha UI does not install this route. */
+export function createProposalReviewHttpHandler(service, options) {
+    const facade = new BizAgentUiFacade(service);
+    return async (req, res) => {
+        res.setHeader('Cache-Control', 'no-store');
+        res.setHeader('Content-Type', 'application/json; charset=utf-8');
+        res.setHeader('X-Content-Type-Options', 'nosniff');
+        if (req.method !== 'GET' && req.method !== 'POST') {
+            res.setHeader('Allow', 'GET, POST');
+            respond(res, 405, 'method-not-allowed');
+            return;
+        }
+        try {
+            const principal = await options.authenticateHuman(req);
+            if (!principal?.userId.trim()) {
+                respond(res, 401, 'authentication-required');
+                return;
+            }
+            if (req.method === 'GET') {
+                const query = new URL(req.url ?? '', 'http://bizagent.local').searchParams;
+                const ownerAddress = parseHomeAddress(query.get('ownerAddress') ?? '');
+                const proposalId = query.get('proposalId') ?? '';
+                const proposal = service.ledger.getProposal(proposalId);
+                if (!proposal || proposal.toAddress !== ownerAddress) {
+                    respond(res, 404, 'proposal-not-found');
+                    return;
+                }
+                const accept = !!(await options.authorizeProposal(req, principal, proposal, 'accept'))?.trim();
+                const reject = !!(await options.authorizeProposal(req, principal, proposal, 'reject'))?.trim();
+                res.statusCode = 200;
+                res.end(JSON.stringify({ actions: { accept, reject } }));
+                return;
+            }
+            if (!await options.authorizeMutation(req, principal)) {
+                respond(res, 403, 'mutation-forbidden');
+                return;
+            }
+            if (!String(req.headers['content-type'] ?? '').toLowerCase().startsWith('application/json')) {
+                respond(res, 415, 'content-type');
+                return;
+            }
+            const input = Decision.parse(await readJson(req));
+            const ownerAddress = parseHomeAddress(input.ownerAddress);
+            const proposal = service.ledger.getProposal(input.proposalId);
+            if (!proposal || proposal.toAddress !== ownerAddress) {
+                respond(res, 404, 'proposal-not-found');
+                return;
+            }
+            const authorityRef = await options.authorizeProposal(req, principal, proposal, input.action);
+            if (!authorityRef?.trim()) {
+                respond(res, 403, 'proposal-forbidden');
+                return;
+            }
+            await service.decideProposalAsHuman({ ...input, ownerAddress,
+                reviewerId: principal.userId, authorityRef });
+            res.statusCode = 200;
+            res.end(JSON.stringify(await facade.home(ownerAddress)));
+        }
+        catch (error) {
+            respond(res, error instanceof z.ZodError || error instanceof RequestError ? 400 : 409, error instanceof z.ZodError || error instanceof RequestError ? 'invalid-request' : 'proposal-conflict');
+        }
+    };
+}
+/** Mount on the local DSH web server behind the loopback Host / same-origin route guard. */
+export function registerProposalReviewRoute(webServer, service, options) {
+    return webServer.register({ kind: 'exact', path: BIZAGENT_PROPOSAL_REVIEW_API,
+        handler: guardLocalRoute(createProposalReviewHttpHandler(service, options)) });
+}
+class RequestError extends Error {
+}
+async function readJson(req) {
+    const parts = [];
+    let bytes = 0;
+    for await (const chunk of req) {
+        const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += part.length;
+        if (bytes > 16 * 1024)
+            throw new RequestError('proposal decision exceeds 16 KiB');
+        parts.push(part);
+    }
+    try {
+        return JSON.parse(Buffer.concat(parts).toString('utf8'));
+    }
+    catch {
+        throw new RequestError('invalid JSON');
+    }
+}
+function respond(res, status, error) {
+    res.statusCode = status;
+    res.end(JSON.stringify({ error }));
+}
+//# sourceMappingURL=proposal-review-transport.js.map

package/lib/route-guard.d.ts

@@ -0,0 +1,31 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Browser-trust fence for every HTTP route this plugin registers on the local DSH web server.
+ *
+ * It mirrors DSH's own API guard: DNS rebinding (a page on an attacker domain resolving to
+ * 127.0.0.1) still names the attacker domain in `Host`, so the Host must be loopback; a
+ * cross-site page is rejected by Fetch Metadata; and every mutation must carry an `Origin`
+ * whose host:port equals the `Host`. This is not an authentication layer.
+ */
+export type RouteRejection = 'untrusted-host' | 'cross-site-request' | 'origin-rejected';
+export declare function isLoopbackHostname(hostname: string): boolean;
+/** Return why a request must be rejected, or undefined when it may reach the handler. */
+export declare function localRouteRejection(request: Pick<IncomingMessage, 'method' | 'headers'>): RouteRejection | undefined;
+/** Wrap a route handler so untrusted browser requests get a 403 before any handler code runs. */
+export declare function guardLocalRoute<Req extends IncomingMessage, Res extends ServerResponse>(handler: (request: Req, response: Res) => void | Promise<void>): (request: Req, response: Res) => Promise<void>;
+/** Write the standard 403 response and return true when the request fails the fence. */
+export declare function rejectUntrustedRequest(request: Pick<IncomingMessage, 'method' | 'headers'>, response: Pick<ServerResponse, 'setHeader' | 'end'> & {
+    statusCode: number;
+}): boolean;
+/** DSH Web's own browser login (the cookie minted from the URL `dsh web` prints). */
+export interface OperatorAuthentication {
+    /** 401 or 403 when the request lacks DSH's browser login; undefined when it may proceed. */
+    requestRejection(request: Pick<IncomingMessage, 'headers'>): 401 | 403 | 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 declare function dshOperatorAuthentication(ctx: Context): OperatorAuthentication | undefined;
+//# sourceMappingURL=route-guard.d.ts.map