@buildanagent/harness 0.0.0-stage → 0.1.0-alpha.29
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/LICENSE +54 -0
- package/LICENSE-APACHE +202 -0
- package/LICENSE-MIT +21 -0
- package/README.md +822 -2
- package/dist/ablation.d.ts +2 -0
- package/dist/ablation.js +3 -0
- package/dist/ablation.js.map +1 -0
- package/dist/completion/check.d.ts +64 -0
- package/dist/completion/check.js +152 -0
- package/dist/completion/check.js.map +1 -0
- package/dist/completion/checks.d.ts +45 -0
- package/dist/completion/checks.js +173 -0
- package/dist/completion/checks.js.map +1 -0
- package/dist/completion/flags.d.ts +25 -0
- package/dist/completion/flags.js +87 -0
- package/dist/completion/flags.js.map +1 -0
- package/dist/completion/index.d.ts +8 -0
- package/dist/completion/index.js +9 -0
- package/dist/completion/index.js.map +1 -0
- package/dist/completion/snapshot.d.ts +33 -0
- package/dist/completion/snapshot.js +83 -0
- package/dist/completion/snapshot.js.map +1 -0
- package/dist/context/cap.d.ts +32 -0
- package/dist/context/cap.js +50 -0
- package/dist/context/cap.js.map +1 -0
- package/dist/context/estimate.d.ts +18 -0
- package/dist/context/estimate.js +20 -0
- package/dist/context/estimate.js.map +1 -0
- package/dist/context/file-spill.d.ts +15 -0
- package/dist/context/file-spill.js +40 -0
- package/dist/context/file-spill.js.map +1 -0
- package/dist/context/index.d.ts +10 -0
- package/dist/context/index.js +10 -0
- package/dist/context/index.js.map +1 -0
- package/dist/context/mask.d.ts +27 -0
- package/dist/context/mask.js +71 -0
- package/dist/context/mask.js.map +1 -0
- package/dist/context/mid-turn.d.ts +40 -0
- package/dist/context/mid-turn.js +82 -0
- package/dist/context/mid-turn.js.map +1 -0
- package/dist/context/policy.d.ts +9 -0
- package/dist/context/policy.js +140 -0
- package/dist/context/policy.js.map +1 -0
- package/dist/context/spill-ledger.d.ts +25 -0
- package/dist/context/spill-ledger.js +54 -0
- package/dist/context/spill-ledger.js.map +1 -0
- package/dist/context/spill.d.ts +10 -0
- package/dist/context/spill.js +18 -0
- package/dist/context/spill.js.map +1 -0
- package/dist/context/summarize.d.ts +53 -0
- package/dist/context/summarize.js +204 -0
- package/dist/context/summarize.js.map +1 -0
- package/dist/context/summary-template.d.ts +29 -0
- package/dist/context/summary-template.js +69 -0
- package/dist/context/summary-template.js.map +1 -0
- package/dist/context/types.d.ts +150 -0
- package/dist/context/types.js +2 -0
- package/dist/context/types.js.map +1 -0
- package/dist/context/write-cap.d.ts +19 -0
- package/dist/context/write-cap.js +41 -0
- package/dist/context/write-cap.js.map +1 -0
- package/dist/create-harness.d.ts +7 -0
- package/dist/create-harness.js +21 -0
- package/dist/create-harness.js.map +1 -0
- package/dist/credentials/addresses.d.ts +14 -0
- package/dist/credentials/addresses.js +144 -0
- package/dist/credentials/addresses.js.map +1 -0
- package/dist/credentials/allowlist.d.ts +54 -0
- package/dist/credentials/allowlist.js +134 -0
- package/dist/credentials/allowlist.js.map +1 -0
- package/dist/credentials/egress-policy.d.ts +69 -0
- package/dist/credentials/egress-policy.js +170 -0
- package/dist/credentials/egress-policy.js.map +1 -0
- package/dist/credentials/egress-proxy.d.ts +82 -0
- package/dist/credentials/egress-proxy.js +650 -0
- package/dist/credentials/egress-proxy.js.map +1 -0
- package/dist/credentials/git-route.d.ts +68 -0
- package/dist/credentials/git-route.js +288 -0
- package/dist/credentials/git-route.js.map +1 -0
- package/dist/credentials/index.d.ts +13 -0
- package/dist/credentials/index.js +14 -0
- package/dist/credentials/index.js.map +1 -0
- package/dist/credentials/scrub.d.ts +23 -0
- package/dist/credentials/scrub.js +115 -0
- package/dist/credentials/scrub.js.map +1 -0
- package/dist/errors.d.ts +60 -0
- package/dist/errors.js +67 -0
- package/dist/errors.js.map +1 -0
- package/dist/extensions/compose.d.ts +27 -0
- package/dist/extensions/compose.js +83 -0
- package/dist/extensions/compose.js.map +1 -0
- package/dist/extensions/context-files-node.d.ts +28 -0
- package/dist/extensions/context-files-node.js +74 -0
- package/dist/extensions/context-files-node.js.map +1 -0
- package/dist/extensions/context-files.d.ts +68 -0
- package/dist/extensions/context-files.js +214 -0
- package/dist/extensions/context-files.js.map +1 -0
- package/dist/extensions/digest.d.ts +6 -0
- package/dist/extensions/digest.js +68 -0
- package/dist/extensions/digest.js.map +1 -0
- package/dist/extensions/index.d.ts +10 -0
- package/dist/extensions/index.js +10 -0
- package/dist/extensions/index.js.map +1 -0
- package/dist/extensions/load.d.ts +42 -0
- package/dist/extensions/load.js +211 -0
- package/dist/extensions/load.js.map +1 -0
- package/dist/extensions/lock.d.ts +8 -0
- package/dist/extensions/lock.js +95 -0
- package/dist/extensions/lock.js.map +1 -0
- package/dist/extensions/node.d.ts +10 -0
- package/dist/extensions/node.js +11 -0
- package/dist/extensions/node.js.map +1 -0
- package/dist/extensions/project-dirs.d.ts +24 -0
- package/dist/extensions/project-dirs.js +97 -0
- package/dist/extensions/project-dirs.js.map +1 -0
- package/dist/extensions/skills-node.d.ts +34 -0
- package/dist/extensions/skills-node.js +123 -0
- package/dist/extensions/skills-node.js.map +1 -0
- package/dist/extensions/skills.d.ts +51 -0
- package/dist/extensions/skills.js +175 -0
- package/dist/extensions/skills.js.map +1 -0
- package/dist/extensions/trust-file.d.ts +3 -0
- package/dist/extensions/trust-file.js +62 -0
- package/dist/extensions/trust-file.js.map +1 -0
- package/dist/extensions/trust-store-node.d.ts +10 -0
- package/dist/extensions/trust-store-node.js +33 -0
- package/dist/extensions/trust-store-node.js.map +1 -0
- package/dist/extensions/types.d.ts +42 -0
- package/dist/extensions/types.js +2 -0
- package/dist/extensions/types.js.map +1 -0
- package/dist/harness.d.ts +156 -0
- package/dist/harness.js +2 -0
- package/dist/harness.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp/connection.d.ts +22 -0
- package/dist/mcp/connection.js +267 -0
- package/dist/mcp/connection.js.map +1 -0
- package/dist/mcp/content.d.ts +27 -0
- package/dist/mcp/content.js +177 -0
- package/dist/mcp/content.js.map +1 -0
- package/dist/mcp/errors.d.ts +19 -0
- package/dist/mcp/errors.js +21 -0
- package/dist/mcp/errors.js.map +1 -0
- package/dist/mcp/index.d.ts +10 -0
- package/dist/mcp/index.js +10 -0
- package/dist/mcp/index.js.map +1 -0
- package/dist/mcp/manager.d.ts +7 -0
- package/dist/mcp/manager.js +173 -0
- package/dist/mcp/manager.js.map +1 -0
- package/dist/mcp/record.d.ts +7 -0
- package/dist/mcp/record.js +20 -0
- package/dist/mcp/record.js.map +1 -0
- package/dist/mcp/stdio.d.ts +39 -0
- package/dist/mcp/stdio.js +382 -0
- package/dist/mcp/stdio.js.map +1 -0
- package/dist/mcp/types.d.ts +172 -0
- package/dist/mcp/types.js +2 -0
- package/dist/mcp/types.js.map +1 -0
- package/dist/memory/index.d.ts +2 -0
- package/dist/memory/index.js +3 -0
- package/dist/memory/index.js.map +1 -0
- package/dist/permissions/default-rules.d.ts +7 -0
- package/dist/permissions/default-rules.js +42 -0
- package/dist/permissions/default-rules.js.map +1 -0
- package/dist/permissions/errors.d.ts +11 -0
- package/dist/permissions/errors.js +14 -0
- package/dist/permissions/errors.js.map +1 -0
- package/dist/permissions/index.d.ts +9 -0
- package/dist/permissions/index.js +9 -0
- package/dist/permissions/index.js.map +1 -0
- package/dist/permissions/match.d.ts +33 -0
- package/dist/permissions/match.js +287 -0
- package/dist/permissions/match.js.map +1 -0
- package/dist/permissions/pipeline.d.ts +9 -0
- package/dist/permissions/pipeline.js +235 -0
- package/dist/permissions/pipeline.js.map +1 -0
- package/dist/permissions/rules.d.ts +22 -0
- package/dist/permissions/rules.js +74 -0
- package/dist/permissions/rules.js.map +1 -0
- package/dist/permissions/shadow.d.ts +5 -0
- package/dist/permissions/shadow.js +22 -0
- package/dist/permissions/shadow.js.map +1 -0
- package/dist/permissions/types.d.ts +104 -0
- package/dist/permissions/types.js +2 -0
- package/dist/permissions/types.js.map +1 -0
- package/dist/sandbox/base.d.ts +45 -0
- package/dist/sandbox/base.js +74 -0
- package/dist/sandbox/base.js.map +1 -0
- package/dist/sandbox/docker/index.d.ts +41 -0
- package/dist/sandbox/docker/index.js +497 -0
- package/dist/sandbox/docker/index.js.map +1 -0
- package/dist/sandbox/errors.d.ts +44 -0
- package/dist/sandbox/errors.js +57 -0
- package/dist/sandbox/errors.js.map +1 -0
- package/dist/sandbox/host-files.d.ts +65 -0
- package/dist/sandbox/host-files.js +258 -0
- package/dist/sandbox/host-files.js.map +1 -0
- package/dist/sandbox/index.d.ts +10 -0
- package/dist/sandbox/index.js +10 -0
- package/dist/sandbox/index.js.map +1 -0
- package/dist/sandbox/none.d.ts +17 -0
- package/dist/sandbox/none.js +108 -0
- package/dist/sandbox/none.js.map +1 -0
- package/dist/sandbox/policy.d.ts +49 -0
- package/dist/sandbox/policy.js +149 -0
- package/dist/sandbox/policy.js.map +1 -0
- package/dist/sandbox/process.d.ts +61 -0
- package/dist/sandbox/process.js +253 -0
- package/dist/sandbox/process.js.map +1 -0
- package/dist/sandbox/spawn-env.d.ts +20 -0
- package/dist/sandbox/spawn-env.js +128 -0
- package/dist/sandbox/spawn-env.js.map +1 -0
- package/dist/sandbox/srt/index.d.ts +38 -0
- package/dist/sandbox/srt/index.js +283 -0
- package/dist/sandbox/srt/index.js.map +1 -0
- package/dist/sandbox/srt/settings.d.ts +60 -0
- package/dist/sandbox/srt/settings.js +84 -0
- package/dist/sandbox/srt/settings.js.map +1 -0
- package/dist/sandbox/types.d.ts +125 -0
- package/dist/sandbox/types.js +6 -0
- package/dist/sandbox/types.js.map +1 -0
- package/dist/server/answers.d.ts +16 -0
- package/dist/server/answers.js +43 -0
- package/dist/server/answers.js.map +1 -0
- package/dist/server/connection.d.ts +99 -0
- package/dist/server/connection.js +309 -0
- package/dist/server/connection.js.map +1 -0
- package/dist/server/dispatcher.d.ts +86 -0
- package/dist/server/dispatcher.js +800 -0
- package/dist/server/dispatcher.js.map +1 -0
- package/dist/server/index.d.ts +13 -0
- package/dist/server/index.js +12 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/local-transport.d.ts +44 -0
- package/dist/server/local-transport.js +103 -0
- package/dist/server/local-transport.js.map +1 -0
- package/dist/server/outbox.d.ts +31 -0
- package/dist/server/outbox.js +130 -0
- package/dist/server/outbox.js.map +1 -0
- package/dist/server/params.d.ts +25 -0
- package/dist/server/params.js +112 -0
- package/dist/server/params.js.map +1 -0
- package/dist/server/protocol.schema.json +2448 -0
- package/dist/server/rpc-session.d.ts +43 -0
- package/dist/server/rpc-session.js +167 -0
- package/dist/server/rpc-session.js.map +1 -0
- package/dist/server/stdio-streams.d.ts +67 -0
- package/dist/server/stdio-streams.js +218 -0
- package/dist/server/stdio-streams.js.map +1 -0
- package/dist/server/stdio.d.ts +59 -0
- package/dist/server/stdio.js +189 -0
- package/dist/server/stdio.js.map +1 -0
- package/dist/server/websocket.d.ts +106 -0
- package/dist/server/websocket.js +327 -0
- package/dist/server/websocket.js.map +1 -0
- package/dist/session/approvals.d.ts +81 -0
- package/dist/session/approvals.js +217 -0
- package/dist/session/approvals.js.map +1 -0
- package/dist/session/code-call-log.d.ts +42 -0
- package/dist/session/code-call-log.js +63 -0
- package/dist/session/code-call-log.js.map +1 -0
- package/dist/session/code-call-result.d.ts +19 -0
- package/dist/session/code-call-result.js +95 -0
- package/dist/session/code-call-result.js.map +1 -0
- package/dist/session/code-call.d.ts +49 -0
- package/dist/session/code-call.js +345 -0
- package/dist/session/code-call.js.map +1 -0
- package/dist/session/effect-scope.d.ts +11 -0
- package/dist/session/effect-scope.js +10 -0
- package/dist/session/effect-scope.js.map +1 -0
- package/dist/session/errors.d.ts +19 -0
- package/dist/session/errors.js +27 -0
- package/dist/session/errors.js.map +1 -0
- package/dist/session/file-index.d.ts +8 -0
- package/dist/session/file-index.js +70 -0
- package/dist/session/file-index.js.map +1 -0
- package/dist/session/file-key-store.d.ts +16 -0
- package/dist/session/file-key-store.js +169 -0
- package/dist/session/file-key-store.js.map +1 -0
- package/dist/session/file-lock.d.ts +52 -0
- package/dist/session/file-lock.js +324 -0
- package/dist/session/file-lock.js.map +1 -0
- package/dist/session/index.d.ts +22 -0
- package/dist/session/index.js +20 -0
- package/dist/session/index.js.map +1 -0
- package/dist/session/jsonl-store.d.ts +37 -0
- package/dist/session/jsonl-store.js +386 -0
- package/dist/session/jsonl-store.js.map +1 -0
- package/dist/session/jsonl.d.ts +9 -0
- package/dist/session/jsonl.js +10 -0
- package/dist/session/jsonl.js.map +1 -0
- package/dist/session/lock.d.ts +19 -0
- package/dist/session/lock.js +2 -0
- package/dist/session/lock.js.map +1 -0
- package/dist/session/memory-store.d.ts +12 -0
- package/dist/session/memory-store.js +60 -0
- package/dist/session/memory-store.js.map +1 -0
- package/dist/session/migrate.d.ts +41 -0
- package/dist/session/migrate.js +86 -0
- package/dist/session/migrate.js.map +1 -0
- package/dist/session/pointer.d.ts +15 -0
- package/dist/session/pointer.js +22 -0
- package/dist/session/pointer.js.map +1 -0
- package/dist/session/rebuild.d.ts +53 -0
- package/dist/session/rebuild.js +230 -0
- package/dist/session/rebuild.js.map +1 -0
- package/dist/session/resume.d.ts +26 -0
- package/dist/session/resume.js +128 -0
- package/dist/session/resume.js.map +1 -0
- package/dist/session/retention.d.ts +97 -0
- package/dist/session/retention.js +702 -0
- package/dist/session/retention.js.map +1 -0
- package/dist/session/runner.d.ts +156 -0
- package/dist/session/runner.js +656 -0
- package/dist/session/runner.js.map +1 -0
- package/dist/session/scheduler.d.ts +47 -0
- package/dist/session/scheduler.js +85 -0
- package/dist/session/scheduler.js.map +1 -0
- package/dist/session/secret-key-store.d.ts +47 -0
- package/dist/session/secret-key-store.js +79 -0
- package/dist/session/secret-key-store.js.map +1 -0
- package/dist/session/session.d.ts +106 -0
- package/dist/session/session.js +353 -0
- package/dist/session/session.js.map +1 -0
- package/dist/session/sticky.d.ts +48 -0
- package/dist/session/sticky.js +232 -0
- package/dist/session/sticky.js.map +1 -0
- package/dist/session/store.d.ts +108 -0
- package/dist/session/store.js +163 -0
- package/dist/session/store.js.map +1 -0
- package/dist/telemetry/index.d.ts +2 -0
- package/dist/telemetry/index.js +3 -0
- package/dist/telemetry/index.js.map +1 -0
- package/dist/testing/fake-sandbox.d.ts +52 -0
- package/dist/testing/fake-sandbox.js +370 -0
- package/dist/testing/fake-sandbox.js.map +1 -0
- package/dist/testing/index.d.ts +10 -0
- package/dist/testing/index.js +11 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/key-store-conformance.d.ts +22 -0
- package/dist/testing/key-store-conformance.js +97 -0
- package/dist/testing/key-store-conformance.js.map +1 -0
- package/dist/testing/run-cases.d.ts +21 -0
- package/dist/testing/run-cases.js +20 -0
- package/dist/testing/run-cases.js.map +1 -0
- package/dist/testing/sandbox-conformance.d.ts +64 -0
- package/dist/testing/sandbox-conformance.js +468 -0
- package/dist/testing/sandbox-conformance.js.map +1 -0
- package/dist/testing/scheduler-conformance.d.ts +32 -0
- package/dist/testing/scheduler-conformance.js +72 -0
- package/dist/testing/scheduler-conformance.js.map +1 -0
- package/dist/testing/store-conformance.d.ts +21 -0
- package/dist/testing/store-conformance.js +320 -0
- package/dist/testing/store-conformance.js.map +1 -0
- package/dist/tools/builtins/bash.d.ts +9 -0
- package/dist/tools/builtins/bash.js +75 -0
- package/dist/tools/builtins/bash.js.map +1 -0
- package/dist/tools/builtins/builtins.d.ts +38 -0
- package/dist/tools/builtins/builtins.js +48 -0
- package/dist/tools/builtins/builtins.js.map +1 -0
- package/dist/tools/builtins/descriptions.d.ts +69 -0
- package/dist/tools/builtins/descriptions.js +94 -0
- package/dist/tools/builtins/descriptions.js.map +1 -0
- package/dist/tools/builtins/fetch.d.ts +12 -0
- package/dist/tools/builtins/fetch.js +157 -0
- package/dist/tools/builtins/fetch.js.map +1 -0
- package/dist/tools/builtins/files.d.ts +27 -0
- package/dist/tools/builtins/files.js +274 -0
- package/dist/tools/builtins/files.js.map +1 -0
- package/dist/tools/builtins/paths.d.ts +30 -0
- package/dist/tools/builtins/paths.js +62 -0
- package/dist/tools/builtins/paths.js.map +1 -0
- package/dist/tools/builtins/results.d.ts +15 -0
- package/dist/tools/builtins/results.js +31 -0
- package/dist/tools/builtins/results.js.map +1 -0
- package/dist/tools/builtins/search.d.ts +18 -0
- package/dist/tools/builtins/search.js +217 -0
- package/dist/tools/builtins/search.js.map +1 -0
- package/dist/tools/errors.d.ts +13 -0
- package/dist/tools/errors.js +17 -0
- package/dist/tools/errors.js.map +1 -0
- package/dist/tools/index.d.ts +12 -0
- package/dist/tools/index.js +11 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/registry.d.ts +3 -0
- package/dist/tools/registry.js +234 -0
- package/dist/tools/registry.js.map +1 -0
- package/dist/tools/tool-search.d.ts +30 -0
- package/dist/tools/tool-search.js +118 -0
- package/dist/tools/tool-search.js.map +1 -0
- package/dist/tools/types.d.ts +106 -0
- package/dist/tools/types.js +2 -0
- package/dist/tools/types.js.map +1 -0
- package/llms.txt +469 -0
- package/package.json +118 -3
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** The session store's two named errors, each a `HarnessError` with its own code and fields. */
|
|
2
|
+
import { HarnessError } from "../errors.js";
|
|
3
|
+
/**
|
|
4
|
+
* Thrown by `append()` when the log is not in the state the caller expected: `expectedLastId` is stale, an entry id is
|
|
5
|
+
* already stored with different content, or a batch is partly stored out of order. Nothing is written. A caller that
|
|
6
|
+
* lost a race reloads the log and decides again.
|
|
7
|
+
*/
|
|
8
|
+
export declare class ConflictError extends HarnessError {
|
|
9
|
+
readonly name = "ConflictError";
|
|
10
|
+
constructor(why: string);
|
|
11
|
+
}
|
|
12
|
+
/** Thrown by `append()` when an entry's JSON is over the store's bound, which is 64 KiB unless the store sets another. */
|
|
13
|
+
export declare class EntryTooLargeError extends HarnessError {
|
|
14
|
+
readonly name = "EntryTooLargeError";
|
|
15
|
+
readonly entryId: string;
|
|
16
|
+
readonly bytes: number;
|
|
17
|
+
readonly maxBytes: number;
|
|
18
|
+
constructor(entryId: string, bytes: number, maxBytes: number);
|
|
19
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/** The session store's two named errors, each a `HarnessError` with its own code and fields. */
|
|
2
|
+
import { HarnessError } from "../errors.js";
|
|
3
|
+
/**
|
|
4
|
+
* Thrown by `append()` when the log is not in the state the caller expected: `expectedLastId` is stale, an entry id is
|
|
5
|
+
* already stored with different content, or a batch is partly stored out of order. Nothing is written. A caller that
|
|
6
|
+
* lost a race reloads the log and decides again.
|
|
7
|
+
*/
|
|
8
|
+
export class ConflictError extends HarnessError {
|
|
9
|
+
name = "ConflictError";
|
|
10
|
+
constructor(why) {
|
|
11
|
+
super("session_conflict", `the session log changed under this append: ${why}`);
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
/** Thrown by `append()` when an entry's JSON is over the store's bound, which is 64 KiB unless the store sets another. */
|
|
15
|
+
export class EntryTooLargeError extends HarnessError {
|
|
16
|
+
name = "EntryTooLargeError";
|
|
17
|
+
entryId;
|
|
18
|
+
bytes;
|
|
19
|
+
maxBytes;
|
|
20
|
+
constructor(entryId, bytes, maxBytes) {
|
|
21
|
+
super("entry_too_large", `entry "${entryId}" is ${bytes} bytes, over the store's bound of ${maxBytes}; spill large content to a file and keep a reference`);
|
|
22
|
+
this.entryId = entryId;
|
|
23
|
+
this.bytes = bytes;
|
|
24
|
+
this.maxBytes = maxBytes;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/session/errors.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;GAIG;AACH,MAAM,OAAO,aAAc,SAAQ,YAAY;IAC3B,IAAI,GAAG,eAAe,CAAC;IAEzC,YAAY,GAAW;QACrB,KAAK,CAAC,kBAAkB,EAAE,8CAA8C,GAAG,EAAE,CAAC,CAAC;IACjF,CAAC;CACF;AAED,0HAA0H;AAC1H,MAAM,OAAO,kBAAmB,SAAQ,YAAY;IAChC,IAAI,GAAG,oBAAoB,CAAC;IACrC,OAAO,CAAS;IAChB,KAAK,CAAS;IACd,QAAQ,CAAS;IAE1B,YAAY,OAAe,EAAE,KAAa,EAAE,QAAgB;QAC1D,KAAK,CACH,iBAAiB,EACjB,UAAU,OAAO,QAAQ,KAAK,qCAAqC,QAAQ,sDAAsD,CAClI,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF","sourcesContent":["/** The session store's two named errors, each a `HarnessError` with its own code and fields. */\nimport { HarnessError } from \"../errors.js\";\n\n/**\n * Thrown by `append()` when the log is not in the state the caller expected: `expectedLastId` is stale, an entry id is\n * already stored with different content, or a batch is partly stored out of order. Nothing is written. A caller that\n * lost a race reloads the log and decides again.\n */\nexport class ConflictError extends HarnessError {\n override readonly name = \"ConflictError\";\n\n constructor(why: string) {\n super(\"session_conflict\", `the session log changed under this append: ${why}`);\n }\n}\n\n/** Thrown by `append()` when an entry's JSON is over the store's bound, which is 64 KiB unless the store sets another. */\nexport class EntryTooLargeError extends HarnessError {\n override readonly name = \"EntryTooLargeError\";\n readonly entryId: string;\n readonly bytes: number;\n readonly maxBytes: number;\n\n constructor(entryId: string, bytes: number, maxBytes: number) {\n super(\n \"entry_too_large\",\n `entry \"${entryId}\" is ${bytes} bytes, over the store's bound of ${maxBytes}; spill large content to a file and keep a reference`,\n );\n this.entryId = entryId;\n this.bytes = bytes;\n this.maxBytes = maxBytes;\n }\n}\n"]}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { SessionIndex } from "./pointer.js";
|
|
2
|
+
/** The options of `fileIndex()`. */
|
|
3
|
+
export interface FileIndexOptions {
|
|
4
|
+
/** The folder that holds the pointers, one folder per user. It can be the session store's folder. */
|
|
5
|
+
readonly dir: string;
|
|
6
|
+
}
|
|
7
|
+
/** A pointer index in files under `options.dir`. */
|
|
8
|
+
export declare function fileIndex(options: FileIndexOptions): SessionIndex;
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `fileIndex()`: a `SessionIndex` that keeps each pointer in a small JSON file beside the session files, replaced by
|
|
3
|
+
* writing a temp file and renaming it over the old one, so a crash leaves the old pointer or the new and never half of one.
|
|
4
|
+
*/
|
|
5
|
+
import { randomUUID } from "node:crypto";
|
|
6
|
+
import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
|
|
7
|
+
import { join } from "node:path";
|
|
8
|
+
import { HarnessError } from "../errors.js";
|
|
9
|
+
import { checkKey, encodeName } from "./store.js";
|
|
10
|
+
const EXTENSION = ".pointer.json";
|
|
11
|
+
const pathOf = (dir, key) => join(dir, encodeName(key.userId), `${encodeName(key.sessionId)}${EXTENSION}`);
|
|
12
|
+
async function flush(path) {
|
|
13
|
+
const handle = await open(path, "r");
|
|
14
|
+
try {
|
|
15
|
+
await handle.sync();
|
|
16
|
+
}
|
|
17
|
+
finally {
|
|
18
|
+
await handle.close();
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
/** A pointer index in files under `options.dir`. */
|
|
22
|
+
export function fileIndex(options) {
|
|
23
|
+
return {
|
|
24
|
+
async get(key) {
|
|
25
|
+
checkKey(key);
|
|
26
|
+
const text = await readFile(pathOf(options.dir, key), "utf8").catch((error) => {
|
|
27
|
+
if (error.code === "ENOENT")
|
|
28
|
+
return undefined;
|
|
29
|
+
throw error;
|
|
30
|
+
});
|
|
31
|
+
if (text === undefined)
|
|
32
|
+
return undefined;
|
|
33
|
+
let file;
|
|
34
|
+
try {
|
|
35
|
+
file = JSON.parse(text).file;
|
|
36
|
+
}
|
|
37
|
+
catch (cause) {
|
|
38
|
+
throw new HarnessError("session_corrupt", "a session pointer is not valid JSON", { cause });
|
|
39
|
+
}
|
|
40
|
+
if (typeof file !== "string")
|
|
41
|
+
throw new HarnessError("session_corrupt", "a session pointer holds no file name");
|
|
42
|
+
return file;
|
|
43
|
+
},
|
|
44
|
+
async set(key, file) {
|
|
45
|
+
checkKey(key);
|
|
46
|
+
const target = pathOf(options.dir, key);
|
|
47
|
+
await mkdir(join(target, ".."), { recursive: true });
|
|
48
|
+
const temp = `${target}.${randomUUID()}.tmp`;
|
|
49
|
+
const handle = await open(temp, "wx");
|
|
50
|
+
try {
|
|
51
|
+
try {
|
|
52
|
+
await handle.writeFile(JSON.stringify({ file }));
|
|
53
|
+
await handle.sync();
|
|
54
|
+
}
|
|
55
|
+
finally {
|
|
56
|
+
await handle.close();
|
|
57
|
+
}
|
|
58
|
+
await rename(temp, target);
|
|
59
|
+
}
|
|
60
|
+
catch (error) {
|
|
61
|
+
// A failed write must not leave its temp file behind. The old pointer is untouched.
|
|
62
|
+
await rm(temp, { force: true });
|
|
63
|
+
throw error;
|
|
64
|
+
}
|
|
65
|
+
// The rename is only durable once the folder is.
|
|
66
|
+
await flush(join(target, "..")).catch(() => undefined);
|
|
67
|
+
},
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
//# sourceMappingURL=file-index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"file-index.js","sourceRoot":"","sources":["../../src/session/file-index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `fileIndex()`: a `SessionIndex` that keeps each pointer in a small JSON file beside the session files, replaced by\n * writing a temp file and renaming it over the old one, so a crash leaves the old pointer or the new and never half of one.\n */\nimport { randomUUID } from \"node:crypto\";\nimport { mkdir, open, readFile, rename, rm } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { HarnessError } from \"../errors.js\";\nimport type { SessionIndex } from \"./pointer.js\";\nimport { checkKey, encodeName, type SessionKey } from \"./store.js\";\n\nconst EXTENSION = \".pointer.json\";\n\n/** The options of `fileIndex()`. */\nexport interface FileIndexOptions {\n /** The folder that holds the pointers, one folder per user. It can be the session store's folder. */\n readonly dir: string;\n}\n\nconst pathOf = (dir: string, key: SessionKey): string =>\n join(dir, encodeName(key.userId), `${encodeName(key.sessionId)}${EXTENSION}`);\n\nasync function flush(path: string): Promise<void> {\n const handle = await open(path, \"r\");\n try {\n await handle.sync();\n } finally {\n await handle.close();\n }\n}\n\n/** A pointer index in files under `options.dir`. */\nexport function fileIndex(options: FileIndexOptions): SessionIndex {\n return {\n async get(key) {\n checkKey(key);\n const text = await readFile(pathOf(options.dir, key), \"utf8\").catch((error: NodeJS.ErrnoException) => {\n if (error.code === \"ENOENT\") return undefined;\n throw error;\n });\n if (text === undefined) return undefined;\n let file: unknown;\n try {\n file = (JSON.parse(text) as { file?: unknown }).file;\n } catch (cause) {\n throw new HarnessError(\"session_corrupt\", \"a session pointer is not valid JSON\", { cause });\n }\n if (typeof file !== \"string\") throw new HarnessError(\"session_corrupt\", \"a session pointer holds no file name\");\n return file;\n },\n async set(key, file) {\n checkKey(key);\n const target = pathOf(options.dir, key);\n await mkdir(join(target, \"..\"), { recursive: true });\n const temp = `${target}.${randomUUID()}.tmp`;\n const handle = await open(temp, \"wx\");\n try {\n try {\n await handle.writeFile(JSON.stringify({ file }));\n await handle.sync();\n } finally {\n await handle.close();\n }\n await rename(temp, target);\n } catch (error) {\n // A failed write must not leave its temp file behind. The old pointer is untouched.\n await rm(temp, { force: true });\n throw error;\n }\n // The rename is only durable once the folder is.\n await flush(join(target, \"..\")).catch(() => undefined);\n },\n };\n}\n"]}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `fileKeyStore()`: a `KeyStore` that keeps the approval key ring in one file, outside every sandbox and outside the
|
|
3
|
+
* session log. The file is created with mode `0600`, in a new folder of mode `0700`, and a ring that group or others can read
|
|
4
|
+
* is refused, because a key anyone can read signs nothing. A change is written to a temp file and renamed over the ring,
|
|
5
|
+
* so a crash leaves the old ring or the new and never half of one.
|
|
6
|
+
*/
|
|
7
|
+
import { type KeyStore } from "@buildanagent/agent-safety";
|
|
8
|
+
/** Where the ring is when no path is given: `$XDG_STATE_HOME/buildanagent/keys.json`, or under `~/.local/state`. */
|
|
9
|
+
export declare function defaultKeyPath(env?: Readonly<Record<string, string | undefined>>): string;
|
|
10
|
+
/**
|
|
11
|
+
* A key ring in the file at `path` (default `defaultKeyPath()`). `load()` creates a ring with one random 256-bit key
|
|
12
|
+
* when the file does not exist yet. `rotate()` adds a new key and makes it current. `prune(inUse)` removes every key
|
|
13
|
+
* not in `inUse` except the current one, and returns the removed ids. `rotate()` and `prune()` take a lock file beside
|
|
14
|
+
* the ring, so two processes that change it together each keep the other's work.
|
|
15
|
+
*/
|
|
16
|
+
export declare function fileKeyStore(path?: string): KeyStore;
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `fileKeyStore()`: a `KeyStore` that keeps the approval key ring in one file, outside every sandbox and outside the
|
|
3
|
+
* session log. The file is created with mode `0600`, in a new folder of mode `0700`, and a ring that group or others can read
|
|
4
|
+
* is refused, because a key anyone can read signs nothing. A change is written to a temp file and renamed over the ring,
|
|
5
|
+
* so a crash leaves the old ring or the new and never half of one.
|
|
6
|
+
*/
|
|
7
|
+
import { Buffer } from "node:buffer";
|
|
8
|
+
import { randomBytes, randomUUID } from "node:crypto";
|
|
9
|
+
import { constants } from "node:fs";
|
|
10
|
+
import { chmod, link, mkdir, open, rename, rm, stat } from "node:fs/promises";
|
|
11
|
+
import { homedir } from "node:os";
|
|
12
|
+
import { dirname, join } from "node:path";
|
|
13
|
+
import process from "node:process";
|
|
14
|
+
import { parseKeyRing } from "@buildanagent/agent-safety";
|
|
15
|
+
import { HarnessError } from "../errors.js";
|
|
16
|
+
const KEY_BYTES = 32;
|
|
17
|
+
/** Where the ring is when no path is given: `$XDG_STATE_HOME/buildanagent/keys.json`, or under `~/.local/state`. */
|
|
18
|
+
export function defaultKeyPath(env = process.env) {
|
|
19
|
+
const state = env.XDG_STATE_HOME !== undefined && env.XDG_STATE_HOME !== ""
|
|
20
|
+
? env.XDG_STATE_HOME
|
|
21
|
+
: join(homedir(), ".local", "state");
|
|
22
|
+
return join(state, "buildanagent", "keys.json");
|
|
23
|
+
}
|
|
24
|
+
const invalid = (message, cause) => new HarnessError("invalid_key_store", message, cause === undefined ? undefined : { cause });
|
|
25
|
+
/** A new key id: the date, then random letters, so two rotations on one day differ and an id reveals no key bytes. */
|
|
26
|
+
function newKeyId(now) {
|
|
27
|
+
return `${now.toISOString().slice(0, 10)}-${randomBytes(4).toString("hex")}`;
|
|
28
|
+
}
|
|
29
|
+
const encodeRing = (ring) => JSON.stringify({
|
|
30
|
+
current: ring.current,
|
|
31
|
+
keys: Object.fromEntries(Object.entries(ring.keys).map(([id, bytes]) => [id, Buffer.from(bytes).toString("base64url")])),
|
|
32
|
+
});
|
|
33
|
+
async function write(path, ring, exclusive) {
|
|
34
|
+
await mkdir(dirname(path), { recursive: true, mode: 0o700 });
|
|
35
|
+
const temp = `${path}.${randomUUID()}.tmp`;
|
|
36
|
+
const handle = await open(temp, "wx", 0o600);
|
|
37
|
+
try {
|
|
38
|
+
try {
|
|
39
|
+
await handle.writeFile(encodeRing(ring));
|
|
40
|
+
await handle.sync();
|
|
41
|
+
}
|
|
42
|
+
finally {
|
|
43
|
+
await handle.close();
|
|
44
|
+
}
|
|
45
|
+
if (exclusive) {
|
|
46
|
+
// A ring another process created in the meantime wins: the link fails and ours is dropped.
|
|
47
|
+
await link(temp, path);
|
|
48
|
+
await rm(temp, { force: true });
|
|
49
|
+
}
|
|
50
|
+
else {
|
|
51
|
+
await rename(temp, path);
|
|
52
|
+
}
|
|
53
|
+
await chmod(path, 0o600);
|
|
54
|
+
}
|
|
55
|
+
catch (error) {
|
|
56
|
+
await rm(temp, { force: true });
|
|
57
|
+
throw error;
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
async function read(path) {
|
|
61
|
+
// One open decides everything: the checks run on the opened file, so the path can't be swapped between check and read.
|
|
62
|
+
const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)).catch((error) => {
|
|
63
|
+
if (error.code === "ENOENT")
|
|
64
|
+
return undefined;
|
|
65
|
+
if (error.code === "ELOOP") {
|
|
66
|
+
throw invalid("the key file is a symbolic link, which could point at a ring someone else wrote");
|
|
67
|
+
}
|
|
68
|
+
throw error;
|
|
69
|
+
});
|
|
70
|
+
if (handle === undefined)
|
|
71
|
+
return undefined;
|
|
72
|
+
try {
|
|
73
|
+
const info = await handle.stat();
|
|
74
|
+
// The file must be ours: in a shared folder another user could put a ring of their own there.
|
|
75
|
+
if (process.platform !== "win32" && info.uid !== process.getuid?.()) {
|
|
76
|
+
throw invalid("the key file belongs to another user");
|
|
77
|
+
}
|
|
78
|
+
// Windows reports a file mode that has no group or other bits to read, so only POSIX systems check it.
|
|
79
|
+
if (process.platform !== "win32" && (info.mode & 0o077) !== 0) {
|
|
80
|
+
throw invalid("the key file can be read by others; run chmod 600 on it, or rotate keys that may have leaked");
|
|
81
|
+
}
|
|
82
|
+
try {
|
|
83
|
+
return parseKeyRing(await handle.readFile("utf8"));
|
|
84
|
+
}
|
|
85
|
+
catch (cause) {
|
|
86
|
+
throw invalid("the key file is not a key ring", cause);
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
finally {
|
|
90
|
+
await handle.close();
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
const LOCK_TRIES = 100;
|
|
94
|
+
const LOCK_WAIT_MS = 50;
|
|
95
|
+
const LOCK_STALE_MS = 60_000;
|
|
96
|
+
/** Runs `change` while this process holds the ring's lock file, so two rotations or prunes can't lose each other's work. */
|
|
97
|
+
async function locked(path, change) {
|
|
98
|
+
await mkdir(dirname(path), { recursive: true, mode: 0o700 });
|
|
99
|
+
const lock = `${path}.lock`;
|
|
100
|
+
for (let attempt = 0;; attempt += 1) {
|
|
101
|
+
try {
|
|
102
|
+
await (await open(lock, "wx", 0o600)).close();
|
|
103
|
+
break;
|
|
104
|
+
}
|
|
105
|
+
catch (error) {
|
|
106
|
+
if (error.code !== "EEXIST")
|
|
107
|
+
throw error;
|
|
108
|
+
// A lock left by a process that died is older than any change takes.
|
|
109
|
+
const age = Date.now() -
|
|
110
|
+
(await stat(lock).then((info) => info.mtimeMs, () => Date.now()));
|
|
111
|
+
if (age > LOCK_STALE_MS)
|
|
112
|
+
await rm(lock, { force: true });
|
|
113
|
+
else if (attempt >= LOCK_TRIES)
|
|
114
|
+
throw invalid("another process is changing the key ring; try again");
|
|
115
|
+
else
|
|
116
|
+
await new Promise((resolve) => setTimeout(resolve, LOCK_WAIT_MS));
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
try {
|
|
120
|
+
return await change();
|
|
121
|
+
}
|
|
122
|
+
finally {
|
|
123
|
+
await rm(lock, { force: true });
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
/**
|
|
127
|
+
* A key ring in the file at `path` (default `defaultKeyPath()`). `load()` creates a ring with one random 256-bit key
|
|
128
|
+
* when the file does not exist yet. `rotate()` adds a new key and makes it current. `prune(inUse)` removes every key
|
|
129
|
+
* not in `inUse` except the current one, and returns the removed ids. `rotate()` and `prune()` take a lock file beside
|
|
130
|
+
* the ring, so two processes that change it together each keep the other's work.
|
|
131
|
+
*/
|
|
132
|
+
export function fileKeyStore(path = defaultKeyPath()) {
|
|
133
|
+
// Plain functions, not methods, so a store passed around as `setInterval(store.rotate, ...)` still works.
|
|
134
|
+
const load = async () => {
|
|
135
|
+
const existing = await read(path);
|
|
136
|
+
if (existing !== undefined)
|
|
137
|
+
return existing;
|
|
138
|
+
const id = newKeyId(new Date());
|
|
139
|
+
const ring = { keys: { [id]: new Uint8Array(randomBytes(KEY_BYTES)) }, current: id };
|
|
140
|
+
try {
|
|
141
|
+
await write(path, ring, true);
|
|
142
|
+
return ring;
|
|
143
|
+
}
|
|
144
|
+
catch (error) {
|
|
145
|
+
if (error.code !== "EEXIST")
|
|
146
|
+
throw error;
|
|
147
|
+
return (await read(path));
|
|
148
|
+
}
|
|
149
|
+
};
|
|
150
|
+
return {
|
|
151
|
+
load,
|
|
152
|
+
rotate: () => locked(path, async () => {
|
|
153
|
+
const ring = await load();
|
|
154
|
+
const id = newKeyId(new Date());
|
|
155
|
+
await write(path, { keys: { ...ring.keys, [id]: new Uint8Array(randomBytes(KEY_BYTES)) }, current: id }, false);
|
|
156
|
+
return id;
|
|
157
|
+
}),
|
|
158
|
+
prune: (inUse) => locked(path, async () => {
|
|
159
|
+
const ring = await load();
|
|
160
|
+
const removed = Object.keys(ring.keys).filter((id) => id !== ring.current && !inUse.has(id));
|
|
161
|
+
if (removed.length === 0)
|
|
162
|
+
return [];
|
|
163
|
+
const kept = Object.fromEntries(Object.entries(ring.keys).filter(([id]) => !removed.includes(id)));
|
|
164
|
+
await write(path, { keys: kept, current: ring.current }, false);
|
|
165
|
+
return removed;
|
|
166
|
+
}),
|
|
167
|
+
};
|
|
168
|
+
}
|
|
169
|
+
//# sourceMappingURL=file-key-store.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"file-key-store.js","sourceRoot":"","sources":["../../src/session/file-key-store.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `fileKeyStore()`: a `KeyStore` that keeps the approval key ring in one file, outside every sandbox and outside the\n * session log. The file is created with mode `0600`, in a new folder of mode `0700`, and a ring that group or others can read\n * is refused, because a key anyone can read signs nothing. A change is written to a temp file and renamed over the ring,\n * so a crash leaves the old ring or the new and never half of one.\n */\n\nimport { Buffer } from \"node:buffer\";\nimport { randomBytes, randomUUID } from \"node:crypto\";\nimport { constants } from \"node:fs\";\nimport { chmod, link, mkdir, open, rename, rm, stat } from \"node:fs/promises\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\nimport process from \"node:process\";\nimport { type KeyRing, type KeyStore, parseKeyRing } from \"@buildanagent/agent-safety\";\nimport { HarnessError } from \"../errors.js\";\n\nconst KEY_BYTES = 32;\n\n/** Where the ring is when no path is given: `$XDG_STATE_HOME/buildanagent/keys.json`, or under `~/.local/state`. */\nexport function defaultKeyPath(env: Readonly<Record<string, string | undefined>> = process.env): string {\n const state =\n env.XDG_STATE_HOME !== undefined && env.XDG_STATE_HOME !== \"\"\n ? env.XDG_STATE_HOME\n : join(homedir(), \".local\", \"state\");\n return join(state, \"buildanagent\", \"keys.json\");\n}\n\nconst invalid = (message: string, cause?: unknown) =>\n new HarnessError(\"invalid_key_store\", message, cause === undefined ? undefined : { cause });\n\n/** A new key id: the date, then random letters, so two rotations on one day differ and an id reveals no key bytes. */\nfunction newKeyId(now: Date): string {\n return `${now.toISOString().slice(0, 10)}-${randomBytes(4).toString(\"hex\")}`;\n}\n\nconst encodeRing = (ring: KeyRing): string =>\n JSON.stringify({\n current: ring.current,\n keys: Object.fromEntries(\n Object.entries(ring.keys).map(([id, bytes]) => [id, Buffer.from(bytes).toString(\"base64url\")]),\n ),\n });\n\nasync function write(path: string, ring: KeyRing, exclusive: boolean): Promise<void> {\n await mkdir(dirname(path), { recursive: true, mode: 0o700 });\n const temp = `${path}.${randomUUID()}.tmp`;\n const handle = await open(temp, \"wx\", 0o600);\n try {\n try {\n await handle.writeFile(encodeRing(ring));\n await handle.sync();\n } finally {\n await handle.close();\n }\n if (exclusive) {\n // A ring another process created in the meantime wins: the link fails and ours is dropped.\n await link(temp, path);\n await rm(temp, { force: true });\n } else {\n await rename(temp, path);\n }\n await chmod(path, 0o600);\n } catch (error) {\n await rm(temp, { force: true });\n throw error;\n }\n}\n\nasync function read(path: string): Promise<KeyRing | undefined> {\n // One open decides everything: the checks run on the opened file, so the path can't be swapped between check and read.\n const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0)).catch(\n (error: NodeJS.ErrnoException) => {\n if (error.code === \"ENOENT\") return undefined;\n if (error.code === \"ELOOP\") {\n throw invalid(\"the key file is a symbolic link, which could point at a ring someone else wrote\");\n }\n throw error;\n },\n );\n if (handle === undefined) return undefined;\n try {\n const info = await handle.stat();\n // The file must be ours: in a shared folder another user could put a ring of their own there.\n if (process.platform !== \"win32\" && info.uid !== process.getuid?.()) {\n throw invalid(\"the key file belongs to another user\");\n }\n // Windows reports a file mode that has no group or other bits to read, so only POSIX systems check it.\n if (process.platform !== \"win32\" && (info.mode & 0o077) !== 0) {\n throw invalid(\"the key file can be read by others; run chmod 600 on it, or rotate keys that may have leaked\");\n }\n try {\n return parseKeyRing(await handle.readFile(\"utf8\"));\n } catch (cause) {\n throw invalid(\"the key file is not a key ring\", cause);\n }\n } finally {\n await handle.close();\n }\n}\n\nconst LOCK_TRIES = 100;\nconst LOCK_WAIT_MS = 50;\nconst LOCK_STALE_MS = 60_000;\n\n/** Runs `change` while this process holds the ring's lock file, so two rotations or prunes can't lose each other's work. */\nasync function locked<T>(path: string, change: () => Promise<T>): Promise<T> {\n await mkdir(dirname(path), { recursive: true, mode: 0o700 });\n const lock = `${path}.lock`;\n for (let attempt = 0; ; attempt += 1) {\n try {\n await (await open(lock, \"wx\", 0o600)).close();\n break;\n } catch (error) {\n if ((error as NodeJS.ErrnoException).code !== \"EEXIST\") throw error;\n // A lock left by a process that died is older than any change takes.\n const age =\n Date.now() -\n (await stat(lock).then(\n (info) => info.mtimeMs,\n () => Date.now(),\n ));\n if (age > LOCK_STALE_MS) await rm(lock, { force: true });\n else if (attempt >= LOCK_TRIES) throw invalid(\"another process is changing the key ring; try again\");\n else await new Promise((resolve) => setTimeout(resolve, LOCK_WAIT_MS));\n }\n }\n try {\n return await change();\n } finally {\n await rm(lock, { force: true });\n }\n}\n\n/**\n * A key ring in the file at `path` (default `defaultKeyPath()`). `load()` creates a ring with one random 256-bit key\n * when the file does not exist yet. `rotate()` adds a new key and makes it current. `prune(inUse)` removes every key\n * not in `inUse` except the current one, and returns the removed ids. `rotate()` and `prune()` take a lock file beside\n * the ring, so two processes that change it together each keep the other's work.\n */\nexport function fileKeyStore(path: string = defaultKeyPath()): KeyStore {\n // Plain functions, not methods, so a store passed around as `setInterval(store.rotate, ...)` still works.\n const load = async (): Promise<KeyRing> => {\n const existing = await read(path);\n if (existing !== undefined) return existing;\n const id = newKeyId(new Date());\n const ring: KeyRing = { keys: { [id]: new Uint8Array(randomBytes(KEY_BYTES)) }, current: id };\n try {\n await write(path, ring, true);\n return ring;\n } catch (error) {\n if ((error as NodeJS.ErrnoException).code !== \"EEXIST\") throw error;\n return (await read(path)) as KeyRing;\n }\n };\n return {\n load,\n rotate: () =>\n locked(path, async () => {\n const ring = await load();\n const id = newKeyId(new Date());\n await write(path, { keys: { ...ring.keys, [id]: new Uint8Array(randomBytes(KEY_BYTES)) }, current: id }, false);\n return id;\n }),\n prune: (inUse) =>\n locked(path, async () => {\n const ring = await load();\n const removed = Object.keys(ring.keys).filter((id) => id !== ring.current && !inUse.has(id));\n if (removed.length === 0) return [];\n const kept = Object.fromEntries(Object.entries(ring.keys).filter(([id]) => !removed.includes(id)));\n await write(path, { keys: kept, current: ring.current }, false);\n return removed;\n }),\n };\n}\n"]}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { SessionLock } from "./lock.js";
|
|
2
|
+
import { type ProcessScheduler } from "./scheduler.js";
|
|
3
|
+
import { type SessionKey } from "./store.js";
|
|
4
|
+
/** What a lock file holds. */
|
|
5
|
+
export interface LockRecord {
|
|
6
|
+
readonly pid: number;
|
|
7
|
+
readonly host: string;
|
|
8
|
+
readonly token: string;
|
|
9
|
+
/** When the lease ends, in milliseconds since the epoch. */
|
|
10
|
+
readonly leaseUntil: number;
|
|
11
|
+
}
|
|
12
|
+
/** The options of `fileLock()` and `unlockSession()`. */
|
|
13
|
+
export interface FileLockOptions {
|
|
14
|
+
/** The folder that holds the lock files, one folder per user. Use the session store's folder or a sibling of it. */
|
|
15
|
+
readonly dir: string;
|
|
16
|
+
/** How long a lock lasts without a renewal. Default 30 seconds. */
|
|
17
|
+
readonly leaseMs?: number;
|
|
18
|
+
/**
|
|
19
|
+
* How often the holder renews. Default 10 seconds or a third of the lease, whichever is less. It must be shorter
|
|
20
|
+
* than the lease.
|
|
21
|
+
*/
|
|
22
|
+
readonly renewMs?: number;
|
|
23
|
+
/** The clock, in milliseconds. A test sets it. */
|
|
24
|
+
readonly now?: () => number;
|
|
25
|
+
/** Whether a process exists on this host. The default signals it with `process.kill(pid, 0)`. */
|
|
26
|
+
readonly isAlive?: (pid: number) => boolean;
|
|
27
|
+
/** This host's name, which a lock from another host is compared with. Default `os.hostname()`. */
|
|
28
|
+
readonly host?: string;
|
|
29
|
+
/** This process's id. Default `process.pid`. */
|
|
30
|
+
readonly pid?: number;
|
|
31
|
+
/**
|
|
32
|
+
* What wakes a hold to renew its lease. Default: a scheduler of this lock's own, which uses timers. A host that shares
|
|
33
|
+
* a scheduler across locks passes it here; each renewal's id starts with `lease:`, so the host's own wakes don't clash.
|
|
34
|
+
*/
|
|
35
|
+
readonly scheduler?: ProcessScheduler;
|
|
36
|
+
}
|
|
37
|
+
/** What `unlockSession()` removed: the lock's record, or `"unreadable"` when the file held no valid record. */
|
|
38
|
+
export type RemovedLock = LockRecord | "unreadable";
|
|
39
|
+
/**
|
|
40
|
+
* Removes a session's lock whatever its state: the library behind `buildanagent session unlock --force`. A lock from
|
|
41
|
+
* another host is never reclaimed by `acquire()`, because this host can't tell whether its process lives, so this is the
|
|
42
|
+
* way to clear one. It returns what it removed, or `undefined` when there was no lock. The caller decides it is safe.
|
|
43
|
+
*/
|
|
44
|
+
export declare function unlockSession(options: Pick<FileLockOptions, "dir">, key: SessionKey): Promise<RemovedLock | undefined>;
|
|
45
|
+
/**
|
|
46
|
+
* A `SessionLock` over lock files in `options.dir`. `acquire()` creates `<user>/<session>.lock` with the exclusive-create
|
|
47
|
+
* flag and writes `{ pid, host, token, leaseUntil }`, and the holder renews the lease every `renewMs`. A second
|
|
48
|
+
* `acquire()` returns `"would_block"` at once. A lock is stale only when its lease has lapsed and, on the same host, its
|
|
49
|
+
* process no longer exists, so `acquire()` never takes a lock whose holder is alive or one from another host; only
|
|
50
|
+
* `unlockSession()` removes those. Readers never lock.
|
|
51
|
+
*/
|
|
52
|
+
export declare function fileLock(options: FileLockOptions): SessionLock;
|