@orkestrel/scaffold 0.0.139 → 0.0.141
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/main.js +86 -26
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-harden/references/bindings.md +2 -1
- package/dist/host/claude/agents/orkestrel.md +51 -51
- package/dist/host/claude/rules/architecture.md +4 -2
- package/dist/host/claude/rules/typescript.md +23 -10
- package/dist/host/configs/policy.ts +174 -11
- package/dist/host/guides/abort.md +2 -0
- package/dist/host/guides/agent.md +447 -531
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/guide.md +10 -2
- package/dist/host/guides/mcp.md +9 -9
- package/dist/host/guides/middleware.md +34 -49
- package/dist/host/guides/ollama.md +44 -12
- package/dist/host/guides/probe.md +1 -2
- package/dist/host/guides/scaffold.md +25 -16
- package/dist/host/guides/server.md +5 -5
- package/dist/host/guides/study.md +2680 -760
- package/dist/host/manifest.json +18 -18
- package/dist/host/scripts/browsers.sh +0 -0
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/npm.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/host/tests/config.test.ts +185 -1
- package/dist/src/core/index.cjs +14 -14
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +14 -14
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +6 -24
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +1 -1
- package/dist/src/server/index.d.ts +1 -1
- package/dist/src/server/index.js +7 -25
- package/dist/src/server/index.js.map +1 -1
- package/package.json +11 -11
|
@@ -273,7 +273,7 @@ The core supplies the entities a browser session and an agent use. Its host-spec
|
|
|
273
273
|
| `BROWSER_DEFAULT_VIEWPORT_HEIGHT` | const | `720` | Sets the default viewport height, `720` pixels. |
|
|
274
274
|
| `BROWSER_DEFAULT_VIEWPORT_WIDTH` | const | `1280` | Sets the default viewport width, `1280` pixels. |
|
|
275
275
|
| `BROWSER_FRAME_WORLD_NAME` | const | `"__orkestrelBrowserFrame"` | Names the isolated world used for iframe evaluation, `'__orkestrelBrowserFrame'`. |
|
|
276
|
-
| `BROWSER_HAR_CREATOR` | const | `Readonly<{ name: "@orkestrel/browser"; version: "0.0.
|
|
276
|
+
| `BROWSER_HAR_CREATOR` | const | `Readonly<{ name: "@orkestrel/browser"; version: "0.0.35"; }>` | Names the tool identity embedded in HAR 1.2 documents. |
|
|
277
277
|
| `BROWSER_KEY_MODIFIERS` | const | `Readonly<Record<string, number>>` | Maps a canonical modifier name to its CDP Input modifier bit value. |
|
|
278
278
|
| `BROWSER_MOUSE_BUTTON_MASKS` | const | `Readonly<Record<BrowserMouseButton, number>>` | Maps each public mouse button to its CDP Input pressed-button bit value. |
|
|
279
279
|
| `BROWSER_NAVIGATION_REASONS` | const | `readonly BrowserNavigationReason[]` | Lists every CDP `Page.ClientNavigationReason` value a page accepts as a navigation's reason, as of Chromium 141; a page reads any other reason as undefined. |
|
|
@@ -128,6 +128,9 @@ workflow paths and usage text come from [`constants.ts`](../src/server/constants
|
|
|
128
128
|
| `SURFACE_HEADER` | const | `readonly string[]` | Lists the uniform `## Surface` table header, column by column, that guide construction requires. |
|
|
129
129
|
| `EXTERNAL_SCHEMES` | const | `readonly string[]` | Lists the link `href` schemes a guides-parity link check skips as external — a link with one of these prefixes (or a bare `#` anchor, handled separately in `isExternalLink`) is never resolved against the filesystem. |
|
|
130
130
|
| `WRAP_WIDTH` | const | `number` | Holds the default character budget a rewritten doc block's description paragraph wraps inside — the greatest number of characters a re-wrapped line may carry, counted from the line's first character with a tab counting as one, so a wrapped line reads `${indent} * ${text}` and never passes that count. |
|
|
131
|
+
| `WIDE_CHARACTER` | const | `RegExp` | Matches one character that occupies two terminal columns: an emoji presentation character other than a regional indicator, or a character of the East Asian wide and fullwidth classes. |
|
|
132
|
+
| `ZERO_WIDTH` | const | `RegExp` | Matches a character that occupies no terminal column: a nonspacing, enclosing, or extending mark, a format character such as a zero width space, a control character, and the Hangul medial and final jamo, less the format and mark characters the formatter counts one column. |
|
|
133
|
+
| `EMOJI_SEQUENCE` | const | `RegExp` | Matches a grapheme cluster the formatter counts two columns whole: a pictograph sequence joined by a zero width joiner, an emoji followed by a skin-tone modifier, an emoji followed by the emoji variation selector, or a keycap that carries that selector. |
|
|
131
134
|
|
|
132
135
|
### Server constants
|
|
133
136
|
|
|
@@ -222,6 +225,8 @@ directly.
|
|
|
222
225
|
| `findDrift` | function | `(guide: GuideInterface, source: SourceInterface) => readonly Drift[]` | Finds every disagreement between a guide and the source it documents, naming both sites: each `## Surface` row against its declaration's description paragraph, each present `Signature` cell against the declaration's computed signature written as a code span, each `## Methods` row against its member's, and the first titled guide fence of a heading against the `@example` block of the same title. An example's compared text is its language on the first line and its body beneath, so a fence that names another language drifts on its own. |
|
|
223
226
|
| `renderSurface` | function | `(symbols: readonly SurfaceSymbol[]) => string` | Renders a uniform `Name \| Kind \| Signature \| Summary` table with one row per symbol, the name as a code span, the keyword as text, and the signature and summary through `buildCell`. An absent signature or summary renders an empty cell, which `extractSurface` reads back as absent. Guide construction refuses an empty signature cell. |
|
|
224
227
|
| `renderMethods` | function | `(group: MethodGroup) => string` | Renders one `## Methods` group — the `####` heading naming the interface as a code span, then a `Name` and `SUMMARY` table with one row per documented member. A member carrying no summary renders an empty cell, which `extractMethods` reads back as an absent summary. |
|
|
228
|
+
| `computeCellWidth` | function | `(text: string) => number` | Measures how many terminal columns `text` occupies the way the checkout's formatter pads a Markdown table cell: each grapheme cluster counts two columns when it is wide — a character of the East Asian wide and fullwidth blocks, an emoji, or a sequence of them — and otherwise one column per character that has a width, with marks, format characters, and control characters counting none. |
|
|
229
|
+
| `renderMarkdownTable` | function | `(table: TableNode) => string` | Renders `table` as the bytes the checkout's formatter writes for it: every column padded to its widest cell, at least three columns wide, each cell justified to its column's alignment, and a delimiter row of dashes the column's width carrying the alignment's colons. |
|
|
225
230
|
| `renderExample` | function | `(example: SourceExample) => string` | Renders one `@example` block as the guide fence it pairs with — an H3 heading carrying the block's title, then a fence carrying its language and its code. An untitled block renders the fence alone, because a fence pairs on its nearest preceding heading and an untitled block claims none. |
|
|
226
231
|
| `buildTable` | function | `(table: TableNode, row: number, column: number, cell: readonly InlineNode[]) => TableNode` | Builds a copy of `table` with one cell's inline content replaced by `cell`. Every other cell keeps its own nodes, so a rewrite touches the one cell it names and the header and the alignment row travel unchanged. |
|
|
227
232
|
| `buildFence` | function | `(example: SourceExample) => CodeBlockNode` | Builds the fenced code block one `@example` block renders as — its code inside a fence carrying its language, and an untagged fence when the block names none. |
|
|
@@ -924,7 +929,10 @@ splices the render over the region through `spliceSpan`. Only the located node's
|
|
|
924
929
|
rewritten, so every byte of the guide outside it travels unchanged. `replaceCell` takes the header
|
|
925
930
|
of the column it writes and the cell's inline content: `--to guide` passes `SUMMARY` with
|
|
926
931
|
`buildCell(summary)` for a summary, and `SIGNATURE` with one code span carrying the computed
|
|
927
|
-
signature, which the render writes with `|` as `\|` and a longer fence around a backtick.
|
|
932
|
+
signature, which the render writes with `|` as `\|` and a longer fence around a backtick. The
|
|
933
|
+
rewritten table renders through `renderMarkdownTable`, which pads every row to the column widths the
|
|
934
|
+
checkout's formatter writes, measured by `computeCellWidth`, so a `--to guide` rewrite leaves a
|
|
935
|
+
guide the formatter's check accepts without a formatter pass.
|
|
928
936
|
|
|
929
937
|
`replaceSummary` and `replaceExample` rewrite one doc block's raw text — its description paragraph,
|
|
930
938
|
or the body of the `@example` tag carrying a given title. `locateComment` is how a caller finds
|
|
@@ -1161,7 +1169,7 @@ const guide =
|
|
|
1161
1169
|
|
|
1162
1170
|
// The guide's text back, with that one cell replaced and every byte outside the table unchanged.
|
|
1163
1171
|
replaceCell(guide, 'function walk', SUMMARY, buildCell('Walks a tree.'))
|
|
1164
|
-
// '## Surface\n\n| Name
|
|
1172
|
+
// '## Surface\n\n| Name | Kind | Signature | Summary |\n| ------ | -------- | ------------ | ------------- |\n| `walk` | function | `() => void` | Walks a tree. |'
|
|
1165
1173
|
replaceCell(guide, 'function phantom', SUMMARY, buildCell('Absent.')) // undefined — no row carries that key
|
|
1166
1174
|
replaceCell(guide, 'function walk', SUMMARY, buildCell('Walks the tree.')) === guide // true — the row already carries it
|
|
1167
1175
|
|
package/dist/host/guides/mcp.md
CHANGED
|
@@ -1158,8 +1158,8 @@ present origin requires an exact entry in the shared `origin.origins` list. A de
|
|
|
1158
1158
|
that validates upstream sets `origin.enabled` to `false` on the one options value passed to
|
|
1159
1159
|
the route and the session middleware. No shared session primitive is composed; the store, mint, and stream are
|
|
1160
1160
|
implemented here. Because the body can only be read once, the middleware
|
|
1161
|
-
|
|
1162
|
-
|
|
1161
|
+
reads `request.clone()` and calls `next()` on the one `Request` the server built,
|
|
1162
|
+
so the downstream route reads the body itself. Omit the
|
|
1163
1163
|
middleware for the byte-identical stateless default. The WebSocket and stdio
|
|
1164
1164
|
transports are inherently one session per connection, so they carry no
|
|
1165
1165
|
session header — `createMCPSession` is for the HTTP transport only.
|
|
@@ -5852,8 +5852,8 @@ the exact statement:
|
|
|
5852
5852
|
response-stream cancellation to `mcp.dispatch`. After origin/body/JSON-RPC/modern-metadata-shape/header
|
|
5853
5853
|
validation, and only for a request that will dispatch, it synchronously calls the optional
|
|
5854
5854
|
`MCPCallerHandler` immediately before dispatch; a defined result is added as asserted
|
|
5855
|
-
`caller`, while absence is omitted. The session middleware
|
|
5856
|
-
headers, and route state
|
|
5855
|
+
`caller`, while absence is omitted. The session middleware calls `next()` on the one `Request` the server built, so the
|
|
5856
|
+
signal, headers, and route state reach the route unchanged; the pump awaits
|
|
5857
5857
|
the async iterator and never polls. An SSE comment is written every configured
|
|
5858
5858
|
`keepalive.interval` (default `DEFAULT_MCP_KEEPALIVE_INTERVAL`), so an idle
|
|
5859
5859
|
streamed response notices a dead client within one interval; this is transport
|
|
@@ -6094,7 +6094,8 @@ the exact statement:
|
|
|
6094
6094
|
while `enabled: false` delegates each site to an upstream validator. A
|
|
6095
6095
|
modern-shaped POST passes straight through with `next()`, ignoring
|
|
6096
6096
|
`Mcp-Session-Id`. Otherwise, for its `path`, it makes the legacy transport
|
|
6097
|
-
stateful across its verbs: a `POST`
|
|
6097
|
+
stateful across its verbs: a `POST` reads its body text from `request.clone()` (an unusable body, used or locked, reads as
|
|
6098
|
+
absent text and passes through to the route) — resolves a session through
|
|
6098
6099
|
`readSessionHeader`; a valid id touches the entry and sets
|
|
6099
6100
|
`context.state.session`; an absent / unknown id whose (guarded) body
|
|
6100
6101
|
parses to an `initialize` request (`isInitializeRequest`) mints a fresh
|
|
@@ -6105,10 +6106,9 @@ the exact statement:
|
|
|
6105
6106
|
Other unresolved requests return `rejectUnknownSession()` (`404`). The candidate is stored
|
|
6106
6107
|
and advertised only after `context.state.initialization` records a successful dispatch
|
|
6107
6108
|
result, independently of JSON or SSE framing. It
|
|
6108
|
-
then
|
|
6109
|
-
|
|
6110
|
-
|
|
6111
|
-
injects that pinned revision when a live-session POST
|
|
6109
|
+
then calls `next()` on that same `Request` — so the route reads the body itself
|
|
6110
|
+
and retains front-middleware state for caller extraction — sets the pinned
|
|
6111
|
+
revision on it when a live-session POST
|
|
6112
6112
|
is headerless, and stamps the response with `MCP_SESSION_HEADER`. A
|
|
6113
6113
|
live-session POST whose `MCP-Protocol-Version` header names a different
|
|
6114
6114
|
revision than the session pinned is `400` + `-32020` — a session negotiates its
|
|
@@ -81,7 +81,6 @@ const handle = compose<State>([security, boundary], async (_request, context) =>
|
|
|
81
81
|
|
|
82
82
|
| Name | Kind | Signature | Summary |
|
|
83
83
|
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
84
|
-
| `ForeignContract` | interface | `{ expected, is }` | Describes a foreign implementation contract an options key admits — the members its published interface declares, checked as that interface declares them. |
|
|
85
84
|
| `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the error-rendering battery. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
86
85
|
| `TelemetryEntry` | interface | `{ method, pathname, status, duration }` | Represents one access-log-style entry `createTelemetry` records after a response settles — the access-log/timing seam's payload shape. |
|
|
87
86
|
| `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
@@ -227,43 +226,31 @@ const handle = compose<State>([security, boundary], async (_request, context) =>
|
|
|
227
226
|
|
|
228
227
|
### Contracts
|
|
229
228
|
|
|
230
|
-
| Name | Kind | Signature
|
|
231
|
-
| ------------------------------- | ----- |
|
|
232
|
-
| `BOUNDARY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { expose?: boolean; report?: (...args: never[]) => unknown; }>>`
|
|
233
|
-
| `TELEMETRY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ record: (...args: never[]) => unknown; } & {}>>`
|
|
234
|
-
| `COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; encodings?: readonly ("deflate" \| "gzip" \| "identity")[]; filter?: (...args: never[]) => unknown; }>>`
|
|
235
|
-
| `NODE_COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; filter?: (...args: never[]) => unknown; }>>`
|
|
236
|
-
| `SECURITY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { frame?: "DENY" \| "SAMEORIGIN" \| false; csp?: string \| false; referrer?: string \| false; permissions?: string \| false; coop?: string \| false; corp?: string \| false; cluster?: string \| false; coep?: string \| boolean; hsts?: string \| boolean; identifier?: false \| Readonly<{} & { trust?: boolean; }>; }>>`
|
|
237
|
-
| `CORS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { origin?: string \| readonly string[]; methods?: readonly string[]; headers?: readonly string[]; }>>`
|
|
238
|
-
| `DEADLINE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ ms: number; } & { status?: number; }>>`
|
|
239
|
-
| `FORWARDED_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ proxies: number; } & {}> \| Readonly<{ trusted: readonly string[]; } & {}>>`
|
|
240
|
-
| `ETAG_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { weak?: boolean; }>>`
|
|
241
|
-
| `BEARER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ verify: (...args: never[]) => unknown; } & { header?: string; scheme?: string; challenge?: { readonly [k: string]: string; }; }>>`
|
|
242
|
-
| `LIMITER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ max: number; window: number; } & { store?: unknown; capacity?: number; key?: (...args: never[]) => unknown; message?: string; clock?: (...args: never[]) => unknown; policy?: boolean; evict?: (...args: never[]) => unknown; }>>`
|
|
243
|
-
| `SESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ transport: unknown; } & { store?: unknown; ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; create?: (...args: never[]) => unknown; mint?: (...args: never[]) => unknown; required?: boolean; clock?: (...args: never[]) => unknown; }>>`
|
|
244
|
-
| `COOKIE_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: unknown; } & { name?: string; cookie?: Readonly<{} & { path?: string; domain?: string; maxAge?: number; httpOnly?: boolean; secure?: boolean; sameSite?: "Lax" \| "None" \| "Strict"; }>; }>>`
|
|
245
|
-
| `HEADER_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { header?: string; }>>`
|
|
246
|
-
| `SESSION_LIMITS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; }>>`
|
|
247
|
-
| `MEMORY_SESSION_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; }>>`
|
|
248
|
-
| `MEMORY_LIMITER_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { capacity?: number; evict?: (...args: never[]) => unknown; }>>`
|
|
249
|
-
| `CSRF_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: unknown; } & { cookie?: string; header?: string; field?: string; safe?: readonly string[]; }>>`
|
|
250
|
-
| `SCOPE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ paths: string \| readonly string[]; handler: (...args: never[]) => unknown; } & {}>>`
|
|
251
|
-
| `ASSET_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ source: unknown; } & { store?: unknown; }>>`
|
|
252
|
-
| `STATIC_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ root: string; } & { prefix?: string; index?: string; dotfiles?: "allow" \| "deny" \| "ignore"; cache?: number; etag?: boolean; fallback?: boolean \| Readonly<{} & { exclude?: string; }>; }>>`
|
|
253
|
-
| `MULTIPART_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { limits?: Readonly<{} & { file?: Readonly<{} & { size?: number; count?: number; }>; field?: Readonly<{} & { size?: number; count?: number; }>; total?: number; }>; allowed?: readonly string[]; directory?: string; }>>`
|
|
254
|
-
| `UPLOADED_FILE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ field: string; name: string; size: number; mime: string; validated: boolean; status: "moved" \| "staged"; path: string; } & {}>>`
|
|
255
|
-
| `LIMITER_STORE_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `LimiterOptions.store` declares: `consume`. |
|
|
256
|
-
| `SESSION_TRANSPORT_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `SessionOptions.transport` declares: `read`, `write`, and `clear`. |
|
|
257
|
-
| `SESSION_STORE_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `SessionOptions.store` declares: `get`, `set`, and `delete`. |
|
|
258
|
-
| `SIGNER_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `CookieTransportOptions.signer` and `CSRFOptions.signer` declare: `sign` and `verify`. |
|
|
259
|
-
| `ASSET_SOURCE_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `AssetOptions.source` declares: `read`. |
|
|
260
|
-
| `ASSET_STORE_FOREIGN` | const | `import("./types.js").ForeignContract` | Holds the members `AssetOptions.store` declares: `get`, `set`, and `delete`. |
|
|
261
|
-
|
|
262
|
-
### Combinators
|
|
263
|
-
|
|
264
|
-
| Name | Kind | Signature | Summary |
|
|
265
|
-
| ---------------------- | -------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
266
|
-
| `buildForeignContract` | function | `(members: readonly string[]) => ForeignContract` | Builds a `ForeignContract` whose every declared member is a function — the contract an implementation key admits, such as a store, a transport, or a source. |
|
|
229
|
+
| Name | Kind | Signature | Summary |
|
|
230
|
+
| ------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
231
|
+
| `BOUNDARY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { expose?: boolean; report?: (...args: never[]) => unknown; }>>` | Admits `BoundaryOptions` whole for `createBoundary`: a boolean `expose` and a function `report`. |
|
|
232
|
+
| `TELEMETRY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ record: (...args: never[]) => unknown; } & {}>>` | Admits `TelemetryOptions` whole for `createTelemetry`: a required function `record`. |
|
|
233
|
+
| `COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; encodings?: readonly ("deflate" \| "gzip" \| "identity")[]; filter?: (...args: never[]) => unknown; }>>` | Admits `CompressionOptions` whole for `createCompression`: a non-negative finite `threshold`, an `encodings` array of `Encoding` literals, and a function `filter`. |
|
|
234
|
+
| `NODE_COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; filter?: (...args: never[]) => unknown; }>>` | Admits `NodeCompressionOptions` whole for `createNodeCompression`: a non-negative finite `threshold` and a function `filter`. |
|
|
235
|
+
| `SECURITY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { frame?: "DENY" \| "SAMEORIGIN" \| false; csp?: string \| false; referrer?: string \| false; permissions?: string \| false; coop?: string \| false; corp?: string \| false; cluster?: string \| false; coep?: string \| boolean; hsts?: string \| boolean; identifier?: false \| Readonly<{} & { trust?: boolean; }>; }>>` | Admits `SecurityOptions` whole for `createSecurity`: each header option is a string or `false`, `coep` and `hsts` are a string or a boolean, and `identifier` is `{ trust? }` or `false`. |
|
|
236
|
+
| `CORS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { origin?: string \| readonly string[]; methods?: readonly string[]; headers?: readonly string[]; }>>` | Admits `CORSOptions` whole for `createCORS`: `origin` is a string or a string array, and `methods` and `headers` are string arrays. |
|
|
237
|
+
| `DEADLINE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ ms: number; } & { status?: number; }>>` | Admits `DeadlineOptions` whole for `createDeadline`: an integer `ms` from 1 through 2147483647, the range `@orkestrel/timeout` enforces, and an integer `status` from 200 through 599. |
|
|
238
|
+
| `FORWARDED_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ proxies: number; } & {}> \| Readonly<{ trusted: readonly string[]; } & {}>>` | Admits `ForwardedOptions` whole for `createForwarded`: exactly one of an integer `proxies` of at least 1 or a `trusted` string array. |
|
|
239
|
+
| `ETAG_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { weak?: boolean; }>>` | Admits `ETagOptions` whole for `createETag`: a boolean `weak`. |
|
|
240
|
+
| `BEARER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ verify: (...args: never[]) => unknown; } & { header?: string; scheme?: string; challenge?: { readonly [k: string]: string; }; }>>` | Admits `BearerOptions` whole for `createBearer`: a required function `verify`, string `header` and `scheme`, and a `challenge` record of strings. |
|
|
241
|
+
| `LIMITER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ max: number; window: number; } & { store?: Readonly<{ consume: (...args: never[]) => unknown; } & {}>; capacity?: number; key?: (...args: never[]) => unknown; message?: string; clock?: (...args: never[]) => unknown; policy?: boolean; evict?: (...args: never[]) => unknown; }>>` | Admits `LimiterOptions` whole for `createLimiter`: an integer `max` of at least 1, a positive finite `window`, an integer `capacity` of at least 1, and the declared functions; `store` is an implementation that declares the function `consume`. |
|
|
242
|
+
| `SESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ transport: Readonly<{ read: (...args: never[]) => unknown; write: (...args: never[]) => unknown; clear: (...args: never[]) => unknown; } & {}>; } & { store?: Readonly<{ get: (...args: never[]) => unknown; set: (...args: never[]) => unknown; delete: (...args: never[]) => unknown; } & {}>; ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; create?: (...args: never[]) => unknown; mint?: (...args: never[]) => unknown; required?: boolean; clock?: (...args: never[]) => unknown; }>>` | Admits `SessionOptions` whole for `createSession`: positive finite `ttl` and `lifetime`, an integer `capacity` of at least 1, and the declared functions; `transport` is an implementation that declares the functions `read`, `write`, and `clear`, and `store` one that declares `get`, `set`, and `delete`. |
|
|
243
|
+
| `COOKIE_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: Readonly<{ sign: (...args: never[]) => unknown; verify: (...args: never[]) => unknown; } & {}>; } & { name?: string; cookie?: Readonly<{} & { path?: string; domain?: string; maxAge?: number; httpOnly?: boolean; secure?: boolean; sameSite?: "Lax" \| "None" \| "Strict"; }>; }>>` | Admits `CookieTransportOptions` whole for `createCookieTransport`: a string `name`, a required `signer` implementation that declares the functions `sign` and `verify`, and an owned `cookie` record of the six optional members `@orkestrel/server` declares: string `path` and `domain`, a finite number `maxAge` (a non-finite value writes `Max-Age=NaN` or `Max-Age=Infinity` into `Set-Cookie`), boolean `httpOnly` and `secure`, and a `sameSite` of `'Strict'`, `'Lax'`, or `'None'`. |
|
|
244
|
+
| `HEADER_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { header?: string; }>>` | Admits `HeaderTransportOptions` whole for `createHeaderTransport`: a string `header`. |
|
|
245
|
+
| `SESSION_LIMITS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; }>>` | Admits `SessionLimits` whole for `createDatabaseSessionStore`: positive finite `ttl` and `lifetime`. |
|
|
246
|
+
| `MEMORY_SESSION_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; }>>` | Admits `MemorySessionStoreOptions` whole for `createMemorySessionStore`: positive finite `ttl` and `lifetime`, an integer `capacity` of at least 1, and a function `evict`. |
|
|
247
|
+
| `MEMORY_LIMITER_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { capacity?: number; evict?: (...args: never[]) => unknown; }>>` | Admits `MemoryLimiterStoreOptions` whole for `createMemoryLimiterStore`: an integer `capacity` of at least 1 and a function `evict`. |
|
|
248
|
+
| `CSRF_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: Readonly<{ sign: (...args: never[]) => unknown; verify: (...args: never[]) => unknown; } & {}>; } & { cookie?: string; header?: string; field?: string; safe?: readonly string[]; }>>` | Admits `CSRFOptions` whole for `createCSRF`: a required `signer` implementation that declares the functions `sign` and `verify`, string `cookie`, `header`, and `field`, and a `safe` string array. |
|
|
249
|
+
| `SCOPE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ paths: string \| readonly string[]; handler: (...args: never[]) => unknown; } & {}>>` | Admits the arguments of `only` and `except` whole: `paths` is a string or a string array, and `handler` is a function. |
|
|
250
|
+
| `ASSET_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ source: Readonly<{ read: (...args: never[]) => unknown; } & {}>; } & { store?: Readonly<{ get: (...args: never[]) => unknown; set: (...args: never[]) => unknown; delete: (...args: never[]) => unknown; } & {}>; }>>` | Admits `AssetOptions` whole for `createAssets`: `source` is an implementation that declares the function `read`, and `store` one that declares `get`, `set`, and `delete`. |
|
|
251
|
+
| `STATIC_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ root: string; } & { prefix?: string; index?: string; dotfiles?: "allow" \| "deny" \| "ignore"; cache?: number; etag?: boolean; fallback?: boolean \| Readonly<{} & { exclude?: string; }>; }>>` | Admits `StaticOptions` whole for `createStatic`: a non-empty string `root`, a non-negative finite `cache`, a `dotfiles` literal, and a `fallback` that is a boolean or `{ exclude? }`. |
|
|
252
|
+
| `MULTIPART_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { limits?: Readonly<{} & { file?: Readonly<{} & { size?: number; count?: number; }>; field?: Readonly<{} & { size?: number; count?: number; }>; total?: number; }>; allowed?: readonly string[]; directory?: string; }>>` | Admits `MultipartOptions` whole for `createMultipart`: non-negative finite sizes and totals, non-negative integer counts, a string array `allowed`, and a string `directory`. |
|
|
253
|
+
| `UPLOADED_FILE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ field: string; name: string; size: number; mime: string; validated: boolean; status: "moved" \| "staged"; path: string; } & {}>>` | Admits one `UploadedFile` whole for `createUploadedFile`: string `field`, `name`, `mime`, and `path`, a non-negative finite `size`, a boolean `validated`, and a `status` literal. |
|
|
267
254
|
|
|
268
255
|
### Shapers
|
|
269
256
|
|
|
@@ -298,8 +285,7 @@ const handle = compose<State>([security, boundary], async (_request, context) =>
|
|
|
298
285
|
| `verifyCSRFToken` | function | `(signer: SignerInterface, binding: string, token: string) => Promise<boolean>` | Verifies a CSRF token against `binding`: the token's random part must match `CSRF_NONCE_PATTERN`, and its signature must be the signer's HMAC over `CSRF_LABEL`, `binding`, and that random part, under any held key. |
|
|
299
286
|
| `sessionExpired` | function | `(cursors: SessionCursors, now: number, limits: SessionLimits) => boolean` | Checks whether a session has aged past its idle timeout or absolute lifetime as of `now` — the pure expiry predicate `MemorySessionStore` delegates to. |
|
|
300
287
|
| `snapshotSession` | function | `(session: SessionInterface) => SessionSnapshot` | Snapshots a session's `state` into a plain, serializable record — the projection a durable store's `set` writes to disk. |
|
|
301
|
-
| `
|
|
302
|
-
| `admitOptions` | function | `<T>(door: string, contract: ContractInterface<T>, value: unknown) => void` | Admits an options bag whole against its compiled contract, refusing a missing required key, an undeclared key, and a value outside a declared range. |
|
|
288
|
+
| `admitOptions` | function | `<T>(door: string, contract: ContractInterface<T>, value: unknown) => void` | Admits an options bag whole against its compiled contract through the contract's `own`, refusing a missing required key, an undeclared key, a value outside a declared range, and an implementation key that lacks a member its `interfaceShape` declares. |
|
|
303
289
|
| `isPreflight` | function | `(method: string, headers: Headers) => boolean` | Determines whether a request is a CORS preflight — an `OPTIONS` request carrying an `Access-Control-Request-Method` header. |
|
|
304
290
|
| `buildClient` | function | `(ip: string \| undefined) => Client` | Builds the `Client` slice `createForwarded` stashes, from the resolved client IP — a leaf shaping helper. |
|
|
305
291
|
| `equalsConstantTime` | function | `(a: string, b: string) => boolean` | Compares two strings in constant time when their lengths match, so a per-character mismatch never changes how long the comparison takes. |
|
|
@@ -1113,28 +1099,27 @@ still served through the fallback, because the operator configured that path.
|
|
|
1113
1099
|
|
|
1114
1100
|
### Admission: option bags admitted whole
|
|
1115
1101
|
|
|
1116
|
-
Every factory admits its options bag whole through the strict `admitValue` function of `@orkestrel/contract
|
|
1102
|
+
Every factory admits its options bag whole through the `own` method of the compiled contract its options interface declares, which reads the bag one time and refuses as the strict `admitValue` function of `@orkestrel/contract` does, against the compiled contract its options interface declares, before it reads a default. The store classes `MemorySessionStore`, `MemoryLimiterStore`, and `DatabaseSessionStore` admit in their constructors, so a direct `new` call and the factory refuse alike, and their messages lead with the class name. A bag must be a plain object: a class instance, an array, `null`, and a primitive refuse. A bag refuses on an undeclared key such as `origins` for `createCORS`, on a missing required key, on a wrong type, on an explicit `undefined`, and on a number outside its range; a `status` lies from 200 through 599, a `ms` is an integer from 1 through 2147483647 (the range `@orkestrel/timeout` enforces), a size is a non-negative finite number, a count is a non-negative integer, and `NaN` refuses everywhere. An absent bag (`undefined`) admits as `{}`, so a factory with a required key refuses it at that key.
|
|
1117
1103
|
|
|
1118
|
-
Each refusal is a `ContractError`, and the message leads with the factory name. A refusal from `admitOptions` reports the first fault's path in `context.path`, every fault in `cause`, and, for an undeclared key, the declared keys in the message. `createForwarded` admits a union of its two forms, so its refusal carries the root path `[]` and a message that lists both forms.
|
|
1104
|
+
Each refusal is a `ContractError`, and the message leads with the factory name. A refusal from `admitOptions` reports the first fault's path in `context.path`, every fault in `cause`, and, for an undeclared key, the declared keys in the message. `createForwarded` admits a union of its two forms, so its refusal carries the root path `[]` and a message that lists both forms. An implementation key that lacks a declared member reports the member as `context.path`, such as `['store', 'get']`, and a value that is not an object reports the key, such as `['store']`. `renderChallenge` and the `createBearer` refusal of a `challenge` that names `error` report `['scheme']` or `['challenge', name]` as `context.path`, and carry no `cause`.
|
|
1119
1105
|
|
|
1120
|
-
An implementation key (`LimiterOptions.store`, `SessionOptions.transport`, `SessionOptions.store`, `CookieTransportOptions.signer`, `CSRFOptions.signer`, `AssetOptions.source`, and `AssetOptions.store`) is
|
|
1106
|
+
An implementation key (`LimiterOptions.store`, `SessionOptions.transport`, `SessionOptions.store`, `CookieTransportOptions.signer`, `CSRFOptions.signer`, `AssetOptions.source`, and `AssetOptions.store`) is an `interfaceShape` member of the bag's contract. The shape declares each member the published interface lists as a function. It holds a class instance, a callable, and an object whose prototype carries the members by identity, accepts unknown members, reads each declared member one time on admission and at most two times on a refusal, and refuses a missing member or a member that is not a function with one fault per member at the member's path, such as `['store', 'get']`. The same admission that refuses a malformed bag therefore refuses a malformed implementation key. The `cookie` record of `CookieTransportOptions` is an owned plain record the caller writes: the bag's contract admits its six members (`path`, `domain`, `maxAge`, `httpOnly`, `secure`, `sameSite`) and refuses any other key, so `maxage` refuses. `maxAge` is a finite number because a non-finite value writes `Max-Age=NaN` or `Max-Age=Infinity` into `Set-Cookie`.
|
|
1121
1107
|
|
|
1122
1108
|
```ts
|
|
1123
1109
|
import {
|
|
1124
|
-
admitForeign,
|
|
1125
1110
|
admitOptions,
|
|
1126
|
-
buildForeignContract,
|
|
1127
1111
|
CORS_CONTRACT,
|
|
1128
1112
|
DEADLINE_CONTRACT,
|
|
1113
|
+
SESSION_CONTRACT,
|
|
1129
1114
|
} from '@orkestrel/middleware'
|
|
1130
1115
|
|
|
1131
1116
|
admitOptions('createCORS', CORS_CONTRACT, { origin: ['https://app.example'] }) // returns
|
|
1132
1117
|
admitOptions('createCORS', CORS_CONTRACT, { origins: ['https://app.example'] }) // throws a ContractError at ['origins']
|
|
1133
1118
|
admitOptions('createDeadline', DEADLINE_CONTRACT, { ms: 1_000, status: 1000 }) // throws a ContractError at ['status']
|
|
1134
1119
|
|
|
1135
|
-
const
|
|
1136
|
-
|
|
1137
|
-
|
|
1120
|
+
const transport = { read: () => undefined, write: () => undefined, clear: () => undefined }
|
|
1121
|
+
admitOptions('createSession', SESSION_CONTRACT, { transport, store: new Map() }) // returns: a class instance with the members
|
|
1122
|
+
admitOptions('createSession', SESSION_CONTRACT, { transport, store: {} }) // throws a ContractError at ['store', 'get']
|
|
1138
1123
|
```
|
|
1139
1124
|
|
|
1140
1125
|
### Practices
|
|
@@ -1303,7 +1288,7 @@ console.log(extractFieldToken({ csrf: 'credential' }, 'csrf'))
|
|
|
1303
1288
|
`resolveForwardedFor` matrices, `detectEncodings`, `compressBytes`, buffering-eligibility
|
|
1304
1289
|
predicates, `transferSessionState`, `matchesSessionState`, `generateNonce`,
|
|
1305
1290
|
`signCSRFToken` and `verifyCSRFToken` over the malformed-token table, `isPreflight`, `buildClient`,
|
|
1306
|
-
`admitOptions
|
|
1291
|
+
`admitOptions`, traversal and SPA-fallback resolution, byte-signature matching, node zlib
|
|
1307
1292
|
compression, multipart limit resolution, boundary extraction, part-header
|
|
1308
1293
|
parsing, `streamFile`'s pull-driven backpressure and descriptor release, and
|
|
1309
1294
|
the uploaded-file operations, including `moveUploadedFile`'s cross-device
|