@hwp-editor/server 1.0.0-rc.0

package/dist/index.d.ts

@@ -0,0 +1,306 @@
+import { HwpEngine, DocumentHandle, CatEnvelope, RenderOptions, PageImage, EditOp, EditOptions, DocumentSpecV2, ComposeResult, ValidationReport, HwpErrorCode } from '@hwp-editor/core';
+
+/**
+ * CliEngine — HwpEngine implementation that shells out to the hwp-cli binary.
+ *
+ * Hardening ported from the ax deployment wrapper (sites/ax/lib/hwp-cli.ts):
+ * execFile only (never a shell), an owned 60s budget enforced by this
+ * module's own AbortController with SIGTERM-to-SIGKILL escalation (execFile's
+ * built-in `timeout` signals once and never escalates, so a signal-ignoring
+ * child would hang the request past every budget), a 32MB maxBuffer on every
+ * invocation, a scrubbed child environment, and per-call temp directories
+ * that are removed on every path including failure. The runCli promise
+ * settles ONLY from the execFile callback, which fires after the child has
+ * exited; that is what keeps `withWorkDir`'s removal ordered strictly after
+ * child exit, so a racing timer must never settle it. Generalizations: the
+ * binary is resolved by option/env/PATH instead of a bundled artifact (this
+ * package runs on developer machines and servers, not one fixed lambda), and
+ * the per-process verification is a minimum-version check instead of a
+ * pinned checksum (there is no single reviewed artifact here).
+ */
+
+declare const HWP_TIMEOUT_MS = 60000;
+/**
+ * The engine half of the published `HwpErrorCode` vocabulary. Derived with
+ * `Extract<>` rather than aliased to the full union on purpose: an alias
+ * would make `statusFor`'s switch (routes.ts) non-exhaustive by five at
+ * once, and the natural fix for that is a `default:` clause, which
+ * permanently destroys the exhaustiveness check that must catch the next
+ * code addition.
+ *
+ * `cancelled` and `output_too_large` were added in Phase 4. Both are engine
+ * reasons rather than route-layer codes because both are decided inside
+ * `runCli`, from a cause this module owns: only the code that started the
+ * child knows whether it ended because the caller went away or because it
+ * outran the stdout ceiling. A route-layer code would have to re-infer that
+ * from an error shape, which is exactly the guessing this rewrite removed.
+ */
+type HwpCliErrorReason = Extract<HwpErrorCode, "unavailable" | "version" | "timeout" | "failed" | "bad_request" | "unsupported_format" | "protected" | "cancelled" | "output_too_large">;
+/**
+ * Two channels, and which one you use decides who sees it.
+ *
+ * `message` is serialized into the `ErrorResponse` body and crosses the wire
+ * to an untrusted client, so it carries the operation and the outcome and
+ * nothing else — never the resolved binary path, never a staged temp path,
+ * never raw CLI stdout or stderr. `stderr` and `detail` are NOT serialized by
+ * `routes.ts`; they are where that context is retained.
+ *
+ * The scrub is a property of construction rather than a filter applied on the
+ * way out: a filter has to be remembered at every new throw site, and the one
+ * that is forgotten is the one that leaks.
+ *
+ * There is no logger in this package, per the no-`console` convention that
+ * holds across every package source tree. The host catches the error and
+ * decides what to do with `stderr` and `detail` — log them, surface them to
+ * an operator, discard them. This module does not make that choice for it.
+ */
+declare class HwpCliError extends Error {
+    readonly reason: HwpCliErrorReason;
+    /** Raw child stderr, verbatim. Read by `protectedReasonFromStderr`. */
+    readonly stderr?: string | undefined;
+    /** Operator-facing context: the resolved binary path, CLI output. */
+    readonly detail?: string | undefined;
+    constructor(reason: HwpCliErrorReason, message: string, 
+    /** Raw child stderr, verbatim. Read by `protectedReasonFromStderr`. */
+    stderr?: string | undefined, 
+    /** Operator-facing context: the resolved binary path, CLI output. */
+    detail?: string | undefined);
+}
+interface CliEngineOptions {
+    /**
+     * Explicit path to the hwp binary. Resolution order: this option ->
+     * HWP_EDITOR_BIN env -> HWP_CLI env -> `hwp` on PATH.
+     */
+    bin?: string;
+    /**
+     * Per-invocation timeout in ms, default HWP_TIMEOUT_MS. Hosts with a hard
+     * request budget (e.g. a 60s serverless function) should set this a few
+     * seconds below it so the engine's 504 beats the platform's kill.
+     */
+    timeoutMs?: number;
+    /**
+     * Language passed to the child as HWP_LANG, default `en`. Accepts
+     * `en`/`eng`/`english`/`c`/`posix` and `ko`/`kor`/`korean`. This sets
+     * HWP_LANG only: LANG, LC_ALL and LC_MESSAGES stay pinned to `C.UTF-8`
+     * regardless, so a host cannot accidentally change the child's encoding
+     * while changing its language.
+     */
+    locale?: string;
+}
+/** Everything `read` gathers beyond the pinned CatEnvelope wire shape. */
+interface DocumentInspection {
+    envelope: CatEnvelope;
+    /** Raw `hwp fields --json` payload (array), null on failure. */
+    fields: unknown;
+    /** Raw `hwp bookmarks --json` payload (array), null on failure. */
+    bookmarks: unknown;
+    /** Raw `hwp slots --json` payload (object), null on failure. */
+    slots: unknown;
+    /** Raw `hwp info --json` payload, null on failure. */
+    info: unknown;
+    /** Per-document editability derived from `info` (see below). */
+    capabilities: {
+        editable: boolean;
+        reason?: string;
+    };
+}
+/**
+ * Per-call options this transport accepts beyond the `HwpEngine` contract.
+ *
+ * Carried as an extra OPTIONAL trailing parameter on every spawning method,
+ * which keeps each method assignable to its `HwpEngine` counterpart: the
+ * shared interface in `packages/core` is not widened, so the three
+ * transports stay interchangeable.
+ */
+interface CliCallOptions {
+    /**
+     * Aborting this terminates the child (SIGTERM, then SIGKILL after the
+     * grace) and rejects with reason `cancelled`. Route handlers pass
+     * `req.signal` so a client that disconnects does not leave an orphan.
+     */
+    signal?: AbortSignal;
+    /**
+     * Tenant scope from the server's `authorize` hook, salted into every cache
+     * key this engine owns (SEC-04, D-07). One engine instance serves every
+     * request a handler sees, so `inspections` and `snapshots` are otherwise a
+     * cross-tenant channel: two callers uploading identical bytes would share
+     * both entries.
+     *
+     * The engine RECEIVES a scope and never derives one — the single
+     * `authorize` call in routes.ts is the only place it is decided. Omitting
+     * it uses `DEFAULT_CALL_SCOPE`, so a direct `CliEngine` consumer with no
+     * tenancy of its own keeps working unchanged.
+     */
+    scope?: string;
+}
+interface CliEngine extends HwpEngine {
+    /**
+     * Full read pipeline: cat --with-segments plus fields/bookmarks/slots/info.
+     * `read()` is this with the extras dropped, per the pinned wire contract.
+     */
+    describe(document: DocumentHandle, call?: CliCallOptions): Promise<DocumentInspection>;
+    read(document: DocumentHandle, call?: CliCallOptions): Promise<CatEnvelope>;
+    render(document: DocumentHandle, options?: RenderOptions, call?: CliCallOptions): Promise<PageImage[]>;
+    edit(document: DocumentHandle, ops: EditOp[], options?: EditOptions, call?: CliCallOptions): Promise<DocumentHandle>;
+    compose(spec: DocumentSpecV2, name: string, call?: CliCallOptions): Promise<ComposeResult>;
+    validate(document: DocumentHandle, call?: CliCallOptions): Promise<ValidationReport>;
+    /**
+     * Return the pre-edit snapshot of a document this engine edited, or null.
+     * Keyed by the edited document's content hash SALTED WITH THE CALL SCOPE;
+     * consumed on use. Takes the same trailing options as the spawning methods
+     * (it spawns nothing, but its read must salt exactly as `edit`'s write did,
+     * or a scoped write is findable by nobody).
+     */
+    undo(document: DocumentHandle, call?: CliCallOptions): DocumentHandle | null;
+    /** Resolved binary path and verified version. */
+    binaryInfo(): Promise<{
+        bin: string;
+        version: string;
+    }>;
+}
+declare function createCliEngine(opts?: CliEngineOptions): CliEngine;
+
+/**
+ * Server-internal cache of read-pipeline inspections.
+ *
+ * A per-process, in-memory map from an opaque session id to the extras a
+ * `describe()` produced (fields, bookmarks, slots, info, editability), with an
+ * idle TTL swept on growth. It touches the filesystem on no code path and
+ * retains no document bytes: the wire contract (protocol.ts) is stateless, so
+ * every request already carries the document it operates on, and the cache
+ * exists only because opening one document otherwise spawns about seven CLI
+ * processes.
+ *
+ * What this store used to be, and why it is not: it kept the current bytes on
+ * disk, a pre-edit snapshot history (up to twenty full document copies per
+ * session) and an export handle. Nothing in this repository could read any of
+ * it back — no route ever called `undo()` or `exportBytes()`, and protocol.ts
+ * has no session or undo surface — so the history was disk amplification with
+ * no reader (BUG-07, D-05/D-06). Undo lives in the client store,
+ * `packages/core/src/state.ts`, bounded at 50 snapshots, and that is the one
+ * undo model.
+ *
+ * Session ids are UUIDs, never client-supplied paths, and `lookup` still
+ * checks the shape before the map: with no filesystem left there is no path to
+ * confine, but an id from a client is still an id from a client.
+ */
+
+declare const DEFAULT_TTL_MS: number;
+declare class SessionNotFoundError extends Error {
+    constructor(id: string);
+}
+interface DocumentSession {
+    id: string;
+    /** Uploaded document file name (basename only); labelling, never a path. */
+    name: string;
+    createdAt: number;
+    touchedAt: number;
+    /** Cached read-pipeline extras, when the engine provided them. */
+    inspection?: DocumentInspection;
+}
+interface SessionStoreOptions {
+    /** Idle time after which sweep() removes a session. Default 30min. */
+    ttlMs?: number;
+}
+interface SessionStore {
+    /** Register a session for an uploaded document. Bytes are not retained. */
+    create(name: string): DocumentSession;
+    get(id: string): DocumentSession;
+    has(id: string): boolean;
+    attachInspection(id: string, inspection: DocumentInspection): void;
+    /** Remove expired sessions; returns how many were removed. */
+    sweep(now?: number): number;
+    /** Drop every session. */
+    dispose(): void;
+    size(): number;
+    /** All live session ids. */
+    ids(): string[];
+}
+declare function createSessionStore(opts?: SessionStoreOptions): SessionStore;
+
+/**
+ * Framework-agnostic HTTP handler implementing the wire contract of
+ * packages/core/src/protocol.ts as Web Standards `(Request) => Response`.
+ * Framework adapters (next.ts, or any Fetch-API runtime) delegate here.
+ *
+ * Binary payloads cross the wire as base64 inside JSON responses; uploads
+ * are multipart/form-data parsed with Request.formData(). Every failure is
+ * an ErrorResponse with a non-2xx status.
+ *
+ * The admission gate runs in a fixed order before any body is buffered:
+ * action (404) -> method (405) -> authorize (403) -> size (400/413). Only
+ * after all four does a handler touch `req.formData()` or `req.json()`, so a
+ * refusal costs zero uploaded bytes and zero engine calls (D-04).
+ *
+ * Two further checks run after the bytes are in hand, in this order: the
+ * magic-byte sniff at the single buffering site (`sniffFormat`, refusing
+ * anything that is not an HWP or HWPX document, SEC-07), and the op-path
+ * filter in the edit path (refusing `insert-image` and `seal`, which name a
+ * file on the server's own disk, SEC-05). Both still precede the engine call.
+ *
+ * Archive limits — declared entry sizes, decompressed byte ceilings and
+ * compression-ratio caps — are NOT reimplemented here. They are hwp-cli's
+ * default-on `hwp-cli-native-v1` profile (D-12); this handler relies on it,
+ * so bumping the binary means re-checking that the profile still applies.
+ */
+
+/** The six actions this handler serves; the runtime guard and `HwpAction` share it. */
+declare const ACTION_LIST: readonly ["read", "render", "edit", "compose", "validate", "capabilities"];
+/** One of the six action names the handler dispatches on. */
+type HwpAction = (typeof ACTION_LIST)[number];
+/**
+ * Host-supplied admission hook. Its return value answers two questions at
+ * once, deliberately (D-01): a string ADMITS the request AND is the tenant
+ * scope every server-side cache key is salted with; `null` REFUSES it with
+ * HTTP 403 and code `forbidden`. One call decides both, so admission and
+ * tenancy can never disagree.
+ *
+ * Called once per request, awaited, before any body is buffered — a refusal
+ * therefore costs zero bytes of upload and zero engine calls (D-04).
+ *
+ * The refusal message is a fixed literal: a `{ allow, scope, reason }` shape
+ * was rejected precisely so no host-authored reason string can ride out to
+ * an unauthenticated client.
+ */
+type AuthorizeFn = (req: Request, action: HwpAction) => Promise<string | null>;
+interface RoutesOptions {
+    /** Engine to serve; defaults to a CliEngine resolved from env/PATH. */
+    engine?: HwpEngine;
+    /** Convenience for the default engine: explicit hwp binary path. */
+    bin?: string;
+    /** Convenience for the default engine: per-invocation timeout in ms. */
+    timeoutMs?: number;
+    /**
+     * Convenience for the default engine: language passed to the child as
+     * HWP_LANG, default `en`. Accepts `en`/`eng`/`english`/`c`/`posix` and
+     * `ko`/`kor`/`korean`. Applies to the default engine only — an explicit
+     * `engine` carries its own locale.
+     */
+    locale?: string;
+    /**
+     * Largest request admitted, in bytes; defaults to 52428800 (50 MiB).
+     * The figure is the WHOLE request envelope — multipart boundaries, field
+     * names and part headers included — not the document alone, because it is
+     * compared against `Content-Length`. Checked before any buffering; a
+     * request over it is refused with 413 and a request with no measurable
+     * `Content-Length` with 400.
+     */
+    maxRequestBytes?: number;
+    /**
+     * Cache of read-pipeline inspections, keyed by an opaque session id. Pass
+     * false to disable; defaults to a per-handler in-memory store. It retains no
+     * document bytes and touches no filesystem — the wire is stateless and undo
+     * lives in the client store (D-05/D-06).
+     */
+    sessions?: SessionStore | false;
+    /**
+     * Admission hook run before any body is read. Defaults to allow-all with a
+     * fixed scope: this package owns no auth, the host owns the trust boundary
+     * (see the trust-boundary section of packages/server/README.md).
+     */
+    authorize?: AuthorizeFn;
+}
+type HwpEditorHandler = (req: Request) => Promise<Response>;
+declare function createHwpEditorHandler(opts?: RoutesOptions): HwpEditorHandler;
+
+export { type AuthorizeFn, type CliEngine, type CliEngineOptions, DEFAULT_TTL_MS, type DocumentInspection, type DocumentSession, HWP_TIMEOUT_MS, type HwpAction, HwpCliError, type HwpCliErrorReason, type HwpEditorHandler, type RoutesOptions, SessionNotFoundError, type SessionStore, type SessionStoreOptions, createCliEngine, createHwpEditorHandler, createSessionStore };

package/dist/index.js

@@ -0,0 +1,19 @@
+import {
+  DEFAULT_TTL_MS,
+  HWP_TIMEOUT_MS,
+  HwpCliError,
+  SessionNotFoundError,
+  createCliEngine,
+  createHwpEditorHandler,
+  createSessionStore
+} from "./chunk-YJDXTIO7.js";
+export {
+  DEFAULT_TTL_MS,
+  HWP_TIMEOUT_MS,
+  HwpCliError,
+  SessionNotFoundError,
+  createCliEngine,
+  createHwpEditorHandler,
+  createSessionStore
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}