@orkestrel/scaffold 0.0.129 → 0.0.131
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 +39 -36
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +1 -0
- package/dist/host/agents/platforms/windows.md +1 -0
- package/dist/host/agents/skills/orkestrel-parallel/references/t3.md +1 -0
- package/dist/host/agents/skills/orkestrel-polish/SKILL.md +1 -0
- package/dist/host/claude/agents/orkestrel.md +7 -7
- package/dist/host/claude/rules/patterns.md +2 -0
- package/dist/host/guides/agent.md +228 -152
- package/dist/host/guides/capture.md +5 -5
- package/dist/host/guides/middleware.md +82 -64
- package/dist/host/guides/scaffold.md +13 -6
- package/dist/host/manifest.json +11 -11
- package/dist/src/core/index.cjs +69 -18
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +5 -2
- package/dist/src/core/index.d.ts +5 -2
- package/dist/src/core/index.js +69 -18
- package/dist/src/core/index.js.map +1 -1
- package/package.json +1 -1
|
@@ -229,7 +229,7 @@ Engine, runner, preflight, and contact-sheet contracts from [`types.ts`](../src/
|
|
|
229
229
|
| `CaptureSheetsInterface` | interface | `{ execute() }` | Composes exactly the authenticated sparse state and output pairs for iteration review. |
|
|
230
230
|
| `CaptureRegistryArguments` | interface | `{ config, variants, mode? }` | Carries the parsed registry command line: the wrapper, the variants to refresh, and the mode. |
|
|
231
231
|
| `CaptureRegistrarOptions` | interface | `{ root, config, requests, argv, stdout?, stderr?, deadline? }` | Configures one registry refresh: its workspace, wrapper default, request directory, and command line. |
|
|
232
|
-
| `CaptureRegistrarInterface` | interface | `{ execute() }` | Refreshes the accepted registry from one complete capture-free journey
|
|
232
|
+
| `CaptureRegistrarInterface` | interface | `{ execute() }` | Refreshes the accepted registry from one complete capture-free journey stage over the selected variants. |
|
|
233
233
|
| `CaptureInputHandler` | type | `(file: string) => string \| undefined` | Reads a contained input through an owning operation's file snapshot memo. |
|
|
234
234
|
| `CaptureRetractionHandler` | type | `() => void` | Removes one invocation's published request during shutdown. |
|
|
235
235
|
| `CaptureTerminationHandler` | type | `() => Promise<boolean>` | Begins one independent child termination only after request removal has been attempted. |
|
|
@@ -257,7 +257,7 @@ The runner's names and bounds from [`constants.ts`](../src/server/constants.ts).
|
|
|
257
257
|
| `CAPTURE_REPORT_LINES` | const | `Readonly<{ readonly preflight: 'READER'; readonly sheets: 'SHEETS'; }>` | Names the first word of the line a reader prints, followed by its JSON report. |
|
|
258
258
|
| `CAPTURE_SHEET` | const | `Readonly<{ readonly cell: 320; readonly limit: 400; readonly mark: Readonly<{ width: 160; height: 20; present: 220; absent: 20; }>; readonly gap: 12; readonly pairs: 2; readonly rows: 4; }>` | Holds the contact-sheet geometry: how wide a cell shrinks toward, how tall it may grow, the mark that stands in for an unreadable image, the gap between neighbors, and how many cells, rows, and pairs a row and a sheet hold. |
|
|
259
259
|
| `CAPTURE_SHEET_FILES` | const | `Readonly<{ readonly prefix: 'sheet-'; readonly digits: 3; readonly index: 'index.json'; readonly notes: 'index.md'; }>` | Names the contact-sheet files: the sheet prefix and digits, and the two index documents. |
|
|
260
|
-
| `CAPTURE_REGISTRY_STAGE` | const | `"registry"` | Names the stage
|
|
260
|
+
| `CAPTURE_REGISTRY_STAGE` | const | `"registry"` | Names the one stage a registry refresh runs every selected producing variant's complete journey in. |
|
|
261
261
|
| `CAPTURE_REGISTRY_LINE` | const | `"REGISTRY"` | Names the first word of the line the registry refresh prints, followed by its JSON summary. |
|
|
262
262
|
| `CAPTURE_REQUESTS_FLAG` | const | `"CAPTURE_REQUESTS"` | Names the environment variable that carries the absolute request directory to a Vitest child. |
|
|
263
263
|
| `CAPTURE_DISCOVERY` | const | `Readonly<{ readonly phase: 'discover'; readonly description: 'description.json'; readonly arguments: readonly string[]; readonly deadline: 60000; }>` | Holds the discovery exchange's fixed names and bound. |
|
|
@@ -365,7 +365,7 @@ The integrity engine from [`CaptureIntegrity.ts`](../src/server/CaptureIntegrity
|
|
|
365
365
|
| `CaptureSheets` | class | `new (options: CaptureSheetOptions) => CaptureSheetsInterface` | Composes exactly the authenticated sparse state and output pairs for iteration review. |
|
|
366
366
|
| `createCapturePreflight` | function | `(options: CaptureReaderOptions) => CapturePreflightInterface` | Creates the preflight that judges the selected frames' freshness, mixed observations, and coverage. |
|
|
367
367
|
| `createCaptureSheets` | function | `(options: CaptureSheetOptions) => CaptureSheetsInterface` | Creates the contact-sheet writer for the selected frames. |
|
|
368
|
-
| `CaptureRegistrar` | class | `new (options: CaptureRegistrarOptions) => CaptureRegistrarInterface` | Refreshes the accepted registry from one complete capture-free journey
|
|
368
|
+
| `CaptureRegistrar` | class | `new (options: CaptureRegistrarOptions) => CaptureRegistrarInterface` | Refreshes the accepted registry from one complete capture-free journey stage over the selected variants. |
|
|
369
369
|
| `createCaptureRegistrar` | function | `(options: CaptureRegistrarOptions) => CaptureRegistrarInterface` | Creates the registry refresh that runs each producing variant's complete journey and publishes the registry. |
|
|
370
370
|
| `CaptureCLI` | class | `new (options?: CaptureCLIOptions) => CaptureCLIInterface` | Dispatches capture commands and maps usage and evidence refusals to their exit codes. |
|
|
371
371
|
| `createCaptureCLI` | function | `(options?: CaptureCLIOptions) => CaptureCLIInterface` | Creates the executable's command dispatcher over a workspace and injected writers. |
|
|
@@ -646,7 +646,7 @@ A module that cannot be loaded, exports no list of functions, or holds a reader
|
|
|
646
646
|
|
|
647
647
|
### Registry refresh
|
|
648
648
|
|
|
649
|
-
The command that bootstraps or replaces the accepted registry. The stage transaction refuses to run until a registry exists, so the refresh cannot stamp through the engine: it imports complete runs instead. `createCaptureRegistrar` takes the same options as the runner minus the command, and `execute` reads the wrapper through the same `CaptureDiscovery` the runner uses, forwarding `--mode` to discovery, the factory, and
|
|
649
|
+
The command that bootstraps or replaces the accepted registry. The stage transaction refuses to run until a registry exists, so the refresh cannot stamp through the engine: it imports complete runs instead. `createCaptureRegistrar` takes the same options as the runner minus the command, and `execute` reads the wrapper through the same `CaptureDiscovery` the runner uses, forwarding `--mode` to discovery, the factory, and the execution child. It takes the same invocation entity and request file, and runs every selected producing variant in one stage, one Vitest child that receives each variant's project, with the `all` selector, the `journey` command, and no capture variable.
|
|
650
650
|
|
|
651
651
|
Refresh a selected producing variant through the registrar:
|
|
652
652
|
|
|
@@ -666,7 +666,7 @@ const exit = await registrar.execute() // 0 when the registry was published
|
|
|
666
666
|
|
|
667
667
|
**Inherited evidence.** Before any stage, the command reads an existing manifest and lookup journal and checks their schemas. An unreadable or unsupported document refuses the refresh and names the file to inspect and repair before retrying. Publication still authenticates inherited evidence through the integrity engine.
|
|
668
668
|
|
|
669
|
-
**Stages.** The stage
|
|
669
|
+
**Stages.** The one stage is named `registry`, so its reporter is `<requests>/runs/<id>/registry.json` and each variant's record is `<directory>/runs/<id>/registry/<variant>.json`. A partial refresh runs only the named variants in that stage. The command takes each selected project's declared input population and its content hashes before the child starts and again after, and refuses when they differ. A child that exits unsuccessfully refuses the refresh with a message that names the stage and its variants. The command then reads the reporter once and, for each variant, reads the final record, requires it to carry the stage's own request, to name the variant, to fall between the start of the refresh and the end of the reporter, to agree with every collected declaration of that variant, and to be complete, and builds one receipt from them: the variant, the record's time, the reporter's path and digest, the input hashes, and the record's declarations and registry. Every receipt the stage builds names the same reporter and digest.
|
|
670
670
|
|
|
671
671
|
**Publication.** `buildCaptureRegistry` imports the receipts only after each exit is zero and each reporter digest still equals its receipt. The registry is written to a candidate beside `registry.json`, read back through the integrity engine pointed at the candidate, and only then renamed over the target, so a registry the engine would refuse never replaces a good one and the old bytes survive a failed or interrupted refresh. The command prints one `REGISTRY` line of JSON: the file, the digest, the variants in the registry, the variants this run refreshed, and the entry count.
|
|
672
672
|
|
|
@@ -55,8 +55,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
55
55
|
| `createDeadline` | function | `<TState>(options: DeadlineOptions) => MiddlewareHandler<TState>` | Creates the application-level per-request deadline battery. |
|
|
56
56
|
| `createForwarded` | function | `<TState extends ClientState & ConnectionState>(options: ForwardedOptions) => MiddlewareHandler<TState>` | Creates the trusted-proxy client-IP resolver battery — walks `X-Forwarded-For` past the hops its options declare trusted. |
|
|
57
57
|
| `createETag` | function | `<TState>(options?: ETagOptions) => MiddlewareHandler<TState>` | Creates the dynamic response `ETag` + conditional GET battery (RFC 7232). |
|
|
58
|
-
| `createBearer` | function | `<TState extends BearerState>(options: BearerOptions) => MiddlewareHandler<TState>`
|
|
59
|
-
| `createLimiter` | function | `<TState extends BearerState & ClientState & ConnectionState>(options: LimiterOptions<TState>) => MiddlewareHandler<TState>`
|
|
58
|
+
| `createBearer` | function | `<TState extends BearerState<TCredential>, TCredential = string>(options: BearerOptions<TCredential>) => MiddlewareHandler<TState>` | Creates the bearer-token authentication battery — reads the token from its header, resolves its credential through `verify`, and answers each `401` with a `WWW-Authenticate` challenge. |
|
|
59
|
+
| `createLimiter` | function | `<TState extends BearerState<unknown> & ClientState & ConnectionState>(options: LimiterOptions<TState>) => MiddlewareHandler<TState>` | Creates the fixed-window rate-limiting battery — checks a key's budget before consuming it, so one window admits exactly `max` requests. |
|
|
60
60
|
| `createBody` | function | `<TState extends BodyState = BodyState>() => MiddlewareHandler<TState>` | Creates the body-driving battery — eagerly awaits the cached `context.body()` so its throws (or a malformed-JSON `undefined`) surface before the handler runs, and stashes the resolved value onto `BodyState.body`. |
|
|
61
61
|
| `createSession` | function | `<S extends SessionInterface = SessionInterface, TState extends SessionState & ConnectionState = SessionState & ConnectionState>(options: SessionOptions<S, TState>) => MiddlewareHandler<TState>` | Creates the generic session battery — resolves, mints, and persists a session across the request, with a mid-handler `regenerate`/`destroy` control handle. |
|
|
62
62
|
| `createCSRF` | function | `<TState extends CSRFState & SessionState & ConnectionState>(options: CSRFOptions) => MiddlewareHandler<TState>` | Creates the session-bound double-submit CSRF protection battery. |
|
|
@@ -74,60 +74,61 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
74
74
|
|
|
75
75
|
### Types
|
|
76
76
|
|
|
77
|
-
| Name | Kind | Signature
|
|
78
|
-
| --------------------------- | --------- |
|
|
79
|
-
| `BoundaryOptions` | interface | `{ expose?, report? }`
|
|
80
|
-
| `TelemetryEntry` | interface | `{ method, pathname, status, duration }`
|
|
81
|
-
| `TelemetryOptions` | interface | `{ record }`
|
|
82
|
-
| `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }`
|
|
83
|
-
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }`
|
|
84
|
-
| `SecurityIdentifierOptions` | type | `{ readonly trust?: boolean; } \| false`
|
|
85
|
-
| `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }`
|
|
86
|
-
| `CorsOptions` | interface | `{ origin?, methods?, headers? }`
|
|
87
|
-
| `DeadlineOptions` | interface | `{ ms, status? }`
|
|
88
|
-
| `ForwardedOptions` | type | `{ readonly proxies: number; } \| { readonly trusted: readonly string[]; }`
|
|
89
|
-
| `ETagOptions` | interface | `{ weak? }`
|
|
90
|
-
| `BearerOptions` | interface | `{
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
77
|
+
| Name | Kind | Signature | Summary |
|
|
78
|
+
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
|
+
| `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the outermost error-rendering battery. |
|
|
80
|
+
| `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. |
|
|
81
|
+
| `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. |
|
|
82
|
+
| `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }` | Configures `createCompression` — response-body compression. |
|
|
83
|
+
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each of `createCompression` and `createNodeCompression` builds from its own option bag. |
|
|
84
|
+
| `SecurityIdentifierOptions` | type | `{ readonly trust?: boolean; } \| false` | Describes `createSecurity`'s `identifier` sub-option — request-id minting/echo policy, or `false` to disable the feature entirely. |
|
|
85
|
+
| `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }` | Configures `createSecurity` — the security-headers + request-id battery. |
|
|
86
|
+
| `CorsOptions` | interface | `{ origin?, methods?, headers? }` | Configures `createCors` — Cross-Origin Resource Sharing. |
|
|
87
|
+
| `DeadlineOptions` | interface | `{ ms, status? }` | Configures `createDeadline` — the application-level per-request deadline. |
|
|
88
|
+
| `ForwardedOptions` | type | `{ readonly proxies: number; } \| { readonly trusted: readonly string[]; }` | Configures `createForwarded` — the trusted-proxy client-IP resolver. |
|
|
89
|
+
| `ETagOptions` | interface | `{ weak? }` | Configures `createETag` — dynamic response ETag + conditional GET. |
|
|
90
|
+
| `BearerOptions` | interface | `{ verify, header?, scheme?, challenge? }` | Configures `createBearer` — bearer-token authentication. |
|
|
91
|
+
| `BearerVerifyFunction` | type | `(token: string, request: Request) => TCredential \| undefined \| Promise<TCredential \| undefined>` | Verifies a presented bearer token and resolves its credential, or `undefined` to refuse it. |
|
|
92
|
+
| `LimiterOptions` | interface | `{ store?, max, window, capacity?, key?, message?, clock?, policy?, evict? }` | Configures `createLimiter` — fixed-window rate limiting. |
|
|
93
|
+
| `BearerState` | interface | `{ token? }` | Describes the bearer-authentication state slice `createBearer` stashes on `context.state` once a token verifies. |
|
|
94
|
+
| `IdentifierState` | interface | `{ identifier? }` | Describes the request-identifier state slice `createSecurity` stashes when its `identifier` option is enabled. |
|
|
95
|
+
| `Client` | interface | `{ ip? }` | Describes the resolved client connection facts `createForwarded` stashes. |
|
|
96
|
+
| `ClientState` | interface | `{ client? }` | Describes the client-facts state slice `createForwarded` stashes. |
|
|
97
|
+
| `ConnectionState` | interface | `{ connection? }` | Describes the connection-facts state slice `createLimiter`'s default key derivation falls back to when neither `BearerState` nor `ClientState` is present — the raw socket peer surfaced on `context.state` by the server's `state` option. |
|
|
98
|
+
| `SessionInterface` | interface | `{ id, state, set(), delete(), clear() }` | Represents a server-managed session's public surface — an id, its live state, and the mutators that write it. |
|
|
99
|
+
| `SessionControlInterface` | interface | `{ destroyed, successor, regenerate(), destroy() }` | Describes the mid-handler control handle `createSession` stashes alongside the session itself — the OWASP anti-fixation / logout primitives. |
|
|
100
|
+
| `SessionState` | interface | `{ session?, control? }` | Describes the session state slice `createSession` stashes. |
|
|
101
|
+
| `BodyState` | interface | `{ body? }` | Describes the body state slice `createBody` stashes. |
|
|
102
|
+
| `SessionStoreInterface` | interface | `{ get(), set(), delete() }` | Describes the pluggable session persistence seam `createSession`'s `store` option implements — a point-access store keyed by session id. |
|
|
103
|
+
| `SessionTransportInterface` | interface | `{ read(), write(), clear() }` | Describes the transport seam `createSession`'s `transport` option implements — how a session id travels to and from the client (a signed cookie, a header, …). |
|
|
104
|
+
| `SessionOptions` | interface | `{ transport, store?, ttl?, lifetime?, capacity?, evict?, create?, mint?, required?, clock? }` | Configures `createSession` — the generic session battery. |
|
|
105
|
+
| `CookieTransportOptions` | interface | `{ name?, secret, cookie? }` | Configures `createCookieTransport` — the signed-cookie `SessionTransportInterface`. |
|
|
106
|
+
| `HeaderTransportOptions` | interface | `{ header? }` | Configures `createHeaderTransport` — the bare-header `SessionTransportInterface`. |
|
|
107
|
+
| `MemorySessionStoreOptions` | interface | `{ capacity?, evict? }` | Configures `createMemorySessionStore` — the default in-process `SessionStoreInterface`. |
|
|
108
|
+
| `SessionLimits` | interface | `{ ttl?, lifetime? }` | Describes the idle and absolute-lifetime thresholds a session store enforces — `sessionExpired`'s limits argument and both shipped stores' construction options. |
|
|
109
|
+
| `SessionCursors` | interface | `{ seen, created }` | Describes the per-session instants a store stamps and `sessionExpired` measures against. |
|
|
110
|
+
| `SessionRow` | interface | `{ id, session }` | Represents one persisted session row — an opaque snapshot column plus the store-owned idle/absolute-lifetime cursors, the shape a `DatabaseSessionStore`'s backing table holds. |
|
|
111
|
+
| `SessionEntry` | interface | `{ session }` | Represents one in-process session entry — the payload `MemorySessionStore` holds against an id, alongside the same cursors a persisted row carries. |
|
|
112
|
+
| `SessionSnapshot` | interface | `{ id, state }` | Represents a session's serializable projection — the value `snapshotSession` produces and a durable store's `set` writes. |
|
|
113
|
+
| `SessionRestoreFunction` | type | `(value: unknown) => SessionInterface \| undefined` | Rebuilds a session entity from an untrusted stored snapshot, or resolves `undefined` when the value is malformed. |
|
|
114
|
+
| `CSRFState` | interface | `{ csrf? }` | Describes the CSRF state slice `createCSRF` stashes — the raw token a safe-method response exposes for a subsequent mutating request to submit back. |
|
|
115
|
+
| `CSRFOptions` | interface | `{ secret, cookie?, header?, field?, safe? }` | Configures `createCSRF` — session-bound double-submit CSRF protection. |
|
|
116
|
+
| `MultipartFile` | interface | `{ field, name, size, mime, validated, status, path }` | Represents one staged multipart upload's public record — the shape the node-face `createMultipart` battery (`@orkestrel/middleware/server`) produces per uploaded file. |
|
|
117
|
+
| `MultipartBody` | interface | `{ files, fields }` | Describes the parsed multipart request body `createMultipart` stashes — files keyed by their field name, plus every plain text field. |
|
|
118
|
+
| `MultipartState` | interface | `{ multipart? }` | Describes the multipart state slice `createMultipart` stashes. |
|
|
119
|
+
| `AssetRepresentation` | interface | `{ body, encoding? }` | Describes one in-memory asset representation returned by an `AssetSourceInterface`. |
|
|
120
|
+
| `AssetSourceInterface` | interface | `{ read() }` | Reads in-memory assets by decoded, browser-build-relative path. |
|
|
121
|
+
| `AssetOptions` | interface | `{ source, store? }` | Configures `createAssets` — in-memory identity/Brotli asset serving. |
|
|
122
|
+
| `StaticOptions` | interface | `{ root, prefix?, index?, dotfiles?, cache?, etag?, fallback? }` | Configures `createStatic` — node `fs`-backed static file serving. |
|
|
123
|
+
| `MultipartLimitsInput` | interface | `{ file?, field?, total? }` | Describes the caller's partial `MultipartLimits` — `createMultipart`'s `limits` option, with every member optional. |
|
|
124
|
+
| `MultipartLimits` | interface | `{ file, field, total }` | Describes the per-category size/count caps `createMultipart` enforces mid-stream — the effective limits, every documented default already applied. |
|
|
125
|
+
| `MultipartOptions` | interface | `{ limits?, allowed?, directory? }` | Configures `createMultipart` — node `fs`/`os`/`crypto`-backed streaming multipart upload parsing. |
|
|
126
|
+
| `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures `createNodeCompression` — `node:zlib`-backed response compression. |
|
|
127
|
+
| `MultipartErrorCode` | type | `'limit' \| 'malformed' \| 'rejected'` | Names the reason `createMultipart` rejected a request — the machine-readable code `MultipartError` carries and maps onto its HTTP status: `'limit'` → 413, `'malformed'` → 400, `'rejected'` → 415. |
|
|
128
|
+
| `UploadStatus` | type | `'staged' \| 'moved'` | Names the lifecycle stage of one staged upload's temp file. |
|
|
129
|
+
| `UploadedFile` | interface | `{ status }` | Describes one uploaded file's post-parse record — the node-bound, richer sibling of the pure core's `MultipartFile` (identical fields, `status` narrowed to `UploadStatus`). Structurally assignable into `MultipartFile` so a `createMultipart`-built `MultipartBody` satisfies the shared core shape. |
|
|
130
|
+
| `PartHeaders` | interface | `{ name, filename, mime }` | Describes one multipart part's parsed header block — `parsePartHeaders`'s return shape. |
|
|
131
|
+
| `ByteRange` | interface | `{ start, end }` | Describes one inclusive byte range over a file — `streamFile`'s optional `range` argument and the shape `createStatic` builds for a satisfiable `Range` request. |
|
|
131
132
|
|
|
132
133
|
### Store and response types
|
|
133
134
|
|
|
@@ -183,6 +184,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
183
184
|
| `DEFAULT_DEADLINE_STATUS` | const | `503` | Holds `503`, the default response status `createDeadline` returns when its deadline fires first. |
|
|
184
185
|
| `DEFAULT_BEARER_HEADER` | const | `"authorization"` | Names `'authorization'`, the default header `createBearer` reads the token from. |
|
|
185
186
|
| `DEFAULT_BEARER_SCHEME` | const | `"Bearer"` | Names `'Bearer'`, the default scheme prefix `createBearer` strips before verification. |
|
|
187
|
+
| `CHALLENGE_TOKEN` | const | `Readonly<RegExp>` | Matches an RFC 9110 `token`, the form a challenge scheme and an auth-param name take. |
|
|
188
|
+
| `CHALLENGE_VALUE` | const | `Readonly<RegExp>` | Matches the characters RFC 6750 § 3 admits in a quoted auth-param value: `%x20-21 / %x23-5B / %x5D-7E`. |
|
|
186
189
|
| `DEFAULT_LIMITER_CAPACITY` | const | `10000` | Holds `10_000`, the default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. |
|
|
187
190
|
| `DEFAULT_LIMITER_MESSAGE` | const | `"rate limit exceeded"` | Holds `'rate limit exceeded'`, the default 429 body message `createLimiter` sends when a key is over budget. |
|
|
188
191
|
| `DEFAULT_SESSION_CAPACITY` | const | `10000` | Holds `10_000`, the default maximum number of distinct session ids `createMemorySessionStore` tracks before LRU (by last write) eviction. |
|
|
@@ -219,7 +222,8 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
219
222
|
|
|
220
223
|
| Name | Kind | Signature | Summary |
|
|
221
224
|
| ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
222
|
-
| `resolveKey` | function | `(state: BearerState & ClientState & ConnectionState) => string`
|
|
225
|
+
| `resolveKey` | function | `(state: BearerState<unknown> & ClientState & ConnectionState) => string` | Derives `createLimiter`'s default rate-limit bucket key from a request's resolved identity facts. |
|
|
226
|
+
| `renderChallenge` | function | `(scheme: string, parameters?: Readonly<Record<string, string>>) => string` | Renders a `WWW-Authenticate` challenge as the scheme alone, or the scheme followed by quoted auth-params in the record's own key order. |
|
|
223
227
|
| `resolveOptInHeader` | function | `(value: string \| boolean \| undefined, fallback: string) => string \| undefined` | Resolves an opt-in, value-bearing security header — `string \| boolean` (off by default, `true` uses the secure default), the shape `createSecurity`'s `coep`/`hsts` options use, distinct from the plain value-or-`false` shape `resolveSecurityHeader` (the peer substrate) handles. |
|
|
224
228
|
| `buildRetryAfter` | function | `(expiry: number, now: number) => string` | Builds the `Retry-After` header value — whole seconds until a window reset, floored at a minimum of `1`. |
|
|
225
229
|
| `buildRateLimitField` | function | `(remaining: number, expiry: number, now: number) => string` | Builds the draft `RateLimit` structured header field — emitted only when `createLimiter`'s `policy` option is `true`. |
|
|
@@ -450,8 +454,9 @@ prevents:
|
|
|
450
454
|
over the uncompressed representation — hashing the compressed bytes
|
|
451
455
|
would break revalidation the instant the negotiated coding changes.
|
|
452
456
|
11. **`createBearer` sits before `createLimiter`.** The limiter's default key
|
|
453
|
-
derivation prefers `BearerState.token` (the `token:<value>` idiom)
|
|
454
|
-
a client-IP fallback — bearer must have already stashed it.
|
|
457
|
+
derivation prefers a string `BearerState.token` (the `token:<value>` idiom)
|
|
458
|
+
over a client-IP fallback — bearer must have already stashed it. An object
|
|
459
|
+
credential never keys the limiter: the key falls through to the client address.
|
|
455
460
|
12. **`createBody` sits before `createSession`/`createCSRF`.** `createSession`'s
|
|
456
461
|
async `mint` and `createCSRF`'s `_csrf` body-field read both need the
|
|
457
462
|
cached `context.body()` already resolved.
|
|
@@ -469,9 +474,14 @@ prevents:
|
|
|
469
474
|
`crypto.randomUUID()` instead; a custom `csp` string replaces the
|
|
470
475
|
default wholesale (never merges); `X-Content-Type-Options: nosniff` is
|
|
471
476
|
unconditional, with no opt-out.
|
|
472
|
-
16. **Bearer.** `
|
|
473
|
-
|
|
474
|
-
|
|
477
|
+
16. **Bearer.** `createBearer` returns a `401` for a missing, wrong-scheme, or empty token
|
|
478
|
+
and for a credential `verify` refuses, and a throw from `verify` propagates
|
|
479
|
+
unchanged. With `verify: (token) => verifyToken(token, secret)`, `verifyToken` is
|
|
480
|
+
total over garbage, tampered, expired, or empty-rotation input — every failure
|
|
481
|
+
renders `401`, never a crash; verification is constant-time through
|
|
482
|
+
`crypto.subtle.verify`. The `401` is a returned response, so each outer
|
|
483
|
+
battery decorates it and `createBoundary`'s `report` never sees it; read
|
|
484
|
+
refusals from `createTelemetry`'s status.
|
|
475
485
|
17. **Limiter.** The key derivation never reads `X-Forwarded-For` itself (only
|
|
476
486
|
`createForwarded`'s already-resolved `ClientState` does, when mounted) —
|
|
477
487
|
so an unmounted `createForwarded` leaves XFF completely untrusted;
|
|
@@ -566,6 +576,14 @@ prevents:
|
|
|
566
576
|
fail-open. Whichever combinator is used, keep its path set in lockstep
|
|
567
577
|
with the router's actual routes — a route added after the fact and not
|
|
568
578
|
added to the set is silently unscoped.
|
|
579
|
+
26. **Challenge.** Every `401` `createBearer` returns carries a `WWW-Authenticate`
|
|
580
|
+
challenge (RFC 9110 § 15.5.2). A missing, wrong-scheme, or empty token renders
|
|
581
|
+
the configured `challenge` auth-params, and a refused credential adds
|
|
582
|
+
`error="invalid_token"` (RFC 6750 § 3). `renderChallenge` refuses a scheme or
|
|
583
|
+
parameter name that is not a `token`, two names that match ignoring case, and a
|
|
584
|
+
value outside `%x20-21 / %x23-5B / %x5D-7E`; it never escapes or strips. `createBearer`
|
|
585
|
+
refuses a `challenge` that names `error` at construction, because the battery
|
|
586
|
+
owns that parameter.
|
|
569
587
|
|
|
570
588
|
## Patterns
|
|
571
589
|
|
|
@@ -598,7 +616,7 @@ import type {
|
|
|
598
616
|
IdentifierState,
|
|
599
617
|
SessionState,
|
|
600
618
|
} from '@orkestrel/middleware'
|
|
601
|
-
import { compose } from '@orkestrel/server'
|
|
619
|
+
import { compose, verifyToken } from '@orkestrel/server'
|
|
602
620
|
|
|
603
621
|
interface State extends BearerState, ClientState, CSRFState, IdentifierState, SessionState {
|
|
604
622
|
readonly connection?: { readonly ip?: string }
|
|
@@ -613,7 +631,7 @@ const onion = [
|
|
|
613
631
|
createCors({ origin: ['https://app.example'] }),
|
|
614
632
|
createForwarded({ proxies: 1 }),
|
|
615
633
|
createETag(),
|
|
616
|
-
createBearer({
|
|
634
|
+
createBearer({ verify: (token) => verifyToken(token, 'shh') }),
|
|
617
635
|
createLimiter({ max: 100, window: 60_000 }),
|
|
618
636
|
createBody(),
|
|
619
637
|
createSession({ transport: createCookieTransport({ secret: 'shh' }) }),
|
|
@@ -992,22 +992,27 @@ Scaffold writes one part of the manifest rather than advising on it: the writabl
|
|
|
992
992
|
and `prepublishOnly`. Each sheet face adds its `check:src:<face>` and `build:src:<face>` scripts.
|
|
993
993
|
Each occupied framework face adds `check:<axis>:vue` and `build:<axis>:vue`; the application face also adds `dev:vue`.
|
|
994
994
|
Selected showcase pages add `showcase`, `showcase:<framework>`, `build:showcase`, and `build:showcase:<framework>`; application journeys add `test:journey:<framework>`.
|
|
995
|
+
A workspace that plans the application server barrel adds `build:app:barrel`, which has no
|
|
996
|
+
predecessor form. A workspace with the server application adds `serve:build`, which runs `build`
|
|
997
|
+
before `serve` and accepts `npm run build:app:server && npm run serve` as its generated predecessor.
|
|
995
998
|
Its `test:src:<face>` script accepts, as its generated predecessor, the command that ran the project
|
|
996
999
|
without building the face first, and `build:src:styles` accepts the styles-only build as the
|
|
997
1000
|
predecessor of the chain that builds themes after it. A publishing `test` chain joins the region when
|
|
998
1001
|
it matches byte for byte the planned chain with the generated `test:app`, `test:journey`, and framework
|
|
999
1002
|
journey invocations inserted after `test:src`, where that blueprint emitted them before.
|
|
1000
1003
|
`repair` and `overwrite` remove those helper invocations from that exact predecessor.
|
|
1001
|
-
|
|
1002
|
-
the planned chain and
|
|
1003
|
-
|
|
1004
|
+
When the `test` or `build:app` chain is a generated predecessor, which runs fewer steps than
|
|
1005
|
+
the planned chain and runs only planned steps in the planned order, that chain joins the region
|
|
1006
|
+
and `repair` and `overwrite` write the planned chain in its place. That write lands only when
|
|
1004
1007
|
every step the planned chain adds runs a script the manifest declares or the region writes. The
|
|
1005
1008
|
`test:src` and `test:app` aggregates sit outside the region. Only a private workspace's planned
|
|
1006
1009
|
chain invokes `test:app`. A chain whose planned form adds an
|
|
1007
1010
|
aggregate the manifest lacks stays with the package, and the `projects` question keeps its remedy.
|
|
1008
|
-
`audit` reports this chain write only through the `projects` question, so a planned step that
|
|
1011
|
+
`audit` reports this `test` chain write only through the `projects` question, so a planned step that
|
|
1009
1012
|
registers no Vitest project, such as `npm run test:guides`, lands on the next `repair` without an
|
|
1010
|
-
earlier advisory.
|
|
1013
|
+
earlier advisory. `audit` reports no `build:app` chain write, so in a barrel workspace only the
|
|
1014
|
+
`scripts` question's report of a missing `build:app:barrel` script precedes that write. A `test` or
|
|
1015
|
+
`build:app` chain running any other step or order stays maintainer-owned, as do the
|
|
1011
1016
|
`check`, `build`, `dev`, `serve`, `format`, `lint`, `clean`, and `copy` gate chains. A
|
|
1012
1017
|
declared value is overwritten only when it is already the value being written or is a recognized
|
|
1013
1018
|
generated predecessor. The overwrite happens in place,
|
|
@@ -1693,7 +1698,9 @@ A workspace that selects `studies` and the `server` application also builds the
|
|
|
1693
1698
|
`app/server/index.ts`, because `@orkestrel/study` loads the package under study as ES modules. The
|
|
1694
1699
|
`appBarrel` factory, the content-owned `configs/app/vite.barrel.config.ts` wrapper, and the
|
|
1695
1700
|
`build:app:barrel` script exist only under that condition, and `build:app` runs the script after
|
|
1696
|
-
`build:app:server`.
|
|
1701
|
+
`build:app:server`. `serve:build` runs `build` before `serve`, so the barrel, which the server
|
|
1702
|
+
build's emptied `dist/app/server` would otherwise lose, and every browser face the server serves are
|
|
1703
|
+
rebuilt. The build emits the single file `dist/app/server/index.js` with `@app/*` and
|
|
1697
1704
|
`@src/*` specifiers and relative imports inlined, and `node:` and every installed package specifier
|
|
1698
1705
|
left external. It sets `emptyOutDir` to `false`, so `main.cjs` stays byte-identical. A workspace
|
|
1699
1706
|
without both conditions plans none of the three. Scaffold's `tests/src/core/templates.test.ts` builds both entries in a
|
package/dist/host/manifest.json
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"storage": "agents/orchestration.md",
|
|
17
17
|
"destination": ".agents/orchestration.md",
|
|
18
18
|
"executable": false,
|
|
19
|
-
"digest": "
|
|
19
|
+
"digest": "67e49a59459fba935c1948d26c9b9fa48001e96d3b0fe0cee194ed724ea96c35"
|
|
20
20
|
},
|
|
21
21
|
{
|
|
22
22
|
"storage": "agents/platforms/posix.md",
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
"storage": "agents/platforms/windows.md",
|
|
29
29
|
"destination": ".agents/platforms/windows.md",
|
|
30
30
|
"executable": false,
|
|
31
|
-
"digest": "
|
|
31
|
+
"digest": "c852ff9886b2a2d24b8a0d69efe10f58dac37bd217d676c133048c148b5e877e"
|
|
32
32
|
},
|
|
33
33
|
{
|
|
34
34
|
"storage": "agents/skills/enterprise-bootstrap/SKILL.md",
|
|
@@ -430,7 +430,7 @@
|
|
|
430
430
|
"storage": "agents/skills/orkestrel-parallel/references/t3.md",
|
|
431
431
|
"destination": ".agents/skills/orkestrel-parallel/references/t3.md",
|
|
432
432
|
"executable": false,
|
|
433
|
-
"digest": "
|
|
433
|
+
"digest": "1669a45b33f53b6b560a65e64c0a13929e2703c4c907b87789518edf4c1b9a95"
|
|
434
434
|
},
|
|
435
435
|
{
|
|
436
436
|
"storage": "agents/skills/orkestrel-parallel/scripts/cases.ts",
|
|
@@ -448,7 +448,7 @@
|
|
|
448
448
|
"storage": "agents/skills/orkestrel-polish/SKILL.md",
|
|
449
449
|
"destination": ".agents/skills/orkestrel-polish/SKILL.md",
|
|
450
450
|
"executable": false,
|
|
451
|
-
"digest": "
|
|
451
|
+
"digest": "bb30bfc7b29d63176e39e345188e5eec45a14921a40671c9d8a4084c2a2e9512"
|
|
452
452
|
},
|
|
453
453
|
{
|
|
454
454
|
"storage": "agents/skills/orkestrel-polish/agents/openai.yaml",
|
|
@@ -628,7 +628,7 @@
|
|
|
628
628
|
"storage": "claude/agents/orkestrel.md",
|
|
629
629
|
"destination": ".claude/agents/orkestrel.md",
|
|
630
630
|
"executable": false,
|
|
631
|
-
"digest": "
|
|
631
|
+
"digest": "74c10351b39d44a2f59609664a42cfdfdcd7cc7e2839ef037e0221be2d04ca86"
|
|
632
632
|
},
|
|
633
633
|
{
|
|
634
634
|
"storage": "claude/agents/planner.md",
|
|
@@ -700,7 +700,7 @@
|
|
|
700
700
|
"storage": "claude/rules/patterns.md",
|
|
701
701
|
"destination": ".claude/rules/patterns.md",
|
|
702
702
|
"executable": false,
|
|
703
|
-
"digest": "
|
|
703
|
+
"digest": "2ad9c0e6ca3c995fccb1163f52537252b3cc83e2e8ef0ca6365a20811959c942"
|
|
704
704
|
},
|
|
705
705
|
{
|
|
706
706
|
"storage": "claude/rules/portability.md",
|
|
@@ -994,7 +994,7 @@
|
|
|
994
994
|
"storage": "guides/agent.md",
|
|
995
995
|
"destination": "guides/agent.md",
|
|
996
996
|
"executable": false,
|
|
997
|
-
"digest": "
|
|
997
|
+
"digest": "e254fceecdd111c66193ccaa2ec065ceaaba68a3386a1e4c29000fd02ec69ec9"
|
|
998
998
|
},
|
|
999
999
|
{
|
|
1000
1000
|
"storage": "guides/brief.md",
|
|
@@ -1018,7 +1018,7 @@
|
|
|
1018
1018
|
"storage": "guides/capture.md",
|
|
1019
1019
|
"destination": "guides/capture.md",
|
|
1020
1020
|
"executable": false,
|
|
1021
|
-
"digest": "
|
|
1021
|
+
"digest": "07c53b0e17c49a01d9d71546bebf0890f3d340f6cb3a86f8c99a7eafe8edb2bf"
|
|
1022
1022
|
},
|
|
1023
1023
|
{
|
|
1024
1024
|
"storage": "guides/codec.md",
|
|
@@ -1114,7 +1114,7 @@
|
|
|
1114
1114
|
"storage": "guides/middleware.md",
|
|
1115
1115
|
"destination": "guides/middleware.md",
|
|
1116
1116
|
"executable": false,
|
|
1117
|
-
"digest": "
|
|
1117
|
+
"digest": "dad75159938cd6179cc542a480b85e758043ba36d3f94a966f2bb42c3adb4049"
|
|
1118
1118
|
},
|
|
1119
1119
|
{
|
|
1120
1120
|
"storage": "guides/msg.md",
|
|
@@ -1198,7 +1198,7 @@
|
|
|
1198
1198
|
"storage": "guides/scaffold.md",
|
|
1199
1199
|
"destination": "guides/scaffold.md",
|
|
1200
1200
|
"executable": false,
|
|
1201
|
-
"digest": "
|
|
1201
|
+
"digest": "9e17c6cdf212c440be057a5336983488329bb67bd66f334b85624d8e457c034a"
|
|
1202
1202
|
},
|
|
1203
1203
|
{
|
|
1204
1204
|
"storage": "guides/sea.md",
|
|
@@ -1417,5 +1417,5 @@
|
|
|
1417
1417
|
"scripts"
|
|
1418
1418
|
],
|
|
1419
1419
|
"surface": [],
|
|
1420
|
-
"digest": "
|
|
1420
|
+
"digest": "76a071e6da224c1cfef62b9e73f4f08e16b7cf91ff8a68b9a2464da95eaed082"
|
|
1421
1421
|
}
|