@smthrs/kernel 0.0.0-stage → 1.0.0-rc.3

package/dist/esm/test/TestGrantStore.js

@@ -0,0 +1,57 @@
+/**
+ * Deterministic grant-store layers for tests.
+ *
+ * @since 1.0.0-rc.0
+ */
+import { GrantStoreError, permissionDenied } from "@smthrs/capability/Permission";
+import { Effect, Layer } from "effect";
+import { emptyPolicy as closedPolicy } from "../GrantStore.js";
+import { GrantStore, layerNoop } from "../GrantStore.js";
+/**
+ * An allow-all grant store.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerAllow = layerNoop;
+/**
+ * Provides a grant store that denies every capability.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerDeny = (reason = "denied by test") => {
+    const service = GrantStore.of({
+        policy: closedPolicy,
+        check: Effect.fn("GrantStore.check")((capability) => Effect.fail(permissionDenied(capability, reason))),
+        reply: Effect.fn("GrantStore.reply")(() => Effect.fail(new GrantStoreError({ code: "request_not_found" }))),
+        list: Effect.fn("GrantStore.list")(() => Effect.succeed([]))(),
+        grantEnvelope: Effect.fn("GrantStore.grantEnvelope")(() => Effect.void)
+    });
+    return Layer.succeed(GrantStore)(service);
+};
+/**
+ * Provides a grant store whose checks consume a deterministic sequence of
+ * attended-style replies. `once`, `run`, and `remembered` allow the check;
+ * `deny` rejects it. Exhausting the script rejects further checks.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ */
+export const layerScripted = (replies) => Layer.effect(GrantStore, Effect.sync(() => {
+    let index = 0;
+    const service = GrantStore.of({
+        policy: closedPolicy,
+        check: Effect.fn("GrantStore.check")((capability) => Effect.suspend(() => {
+            const reply = replies[index++];
+            return reply !== undefined && reply !== "deny"
+                ? Effect.void
+                : Effect.fail(permissionDenied(capability, reply === undefined ? "permission reply script exhausted" : "permission request denied"));
+        })),
+        reply: Effect.fn("GrantStore.reply")(() => Effect.fail(new GrantStoreError({ code: "request_not_found" }))),
+        list: Effect.fn("GrantStore.list")(() => Effect.succeed([]))(),
+        grantEnvelope: Effect.fn("GrantStore.grantEnvelope")(() => Effect.void)
+    });
+    return service;
+}));
+//# sourceMappingURL=TestGrantStore.js.map

package/dist/esm/test/TestGrantStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestGrantStore.js","sourceRoot":"","sources":["../../../src/test/TestGrantStore.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Deterministic grant-store layers for tests.\n *\n * @since 1.0.0-rc.0\n */\n\nimport { GrantStoreError, permissionDenied } from \"@smthrs/capability/Permission\"\nimport { Effect, Layer } from \"effect\"\nimport { emptyPolicy as closedPolicy } from \"../GrantStore.ts\"\nimport { GrantStore, layerNoop, type Resolution, type Service } from \"../GrantStore.ts\"\n\n/**\n * An allow-all grant store.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerAllow: Layer.Layer<GrantStore> = layerNoop\n\n/**\n * Provides a grant store that denies every capability.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerDeny = (reason = \"denied by test\"): Layer.Layer<GrantStore> => {\n  const service = GrantStore.of({\n    policy: closedPolicy,\n    check: Effect.fn(\"GrantStore.check\")((capability) => Effect.fail(permissionDenied(capability, reason))),\n    reply: Effect.fn(\"GrantStore.reply\")(() => Effect.fail(new GrantStoreError({ code: \"request_not_found\" }))),\n    list: Effect.fn(\"GrantStore.list\")(() => Effect.succeed([]))(),\n    grantEnvelope: Effect.fn(\"GrantStore.grantEnvelope\")(() => Effect.void)\n  })\n  return Layer.succeed(GrantStore)(service)\n}\n\n/**\n * Provides a grant store whose checks consume a deterministic sequence of\n * attended-style replies. `once`, `run`, and `remembered` allow the check;\n * `deny` rejects it. Exhausting the script rejects further checks.\n *\n * @category layers\n * @since 1.0.0-rc.0\n */\nexport const layerScripted = (\n  replies: ReadonlyArray<Resolution>\n): Layer.Layer<GrantStore> =>\n  Layer.effect(\n    GrantStore,\n    Effect.sync(() => {\n      let index = 0\n      const service: Service = GrantStore.of({\n        policy: closedPolicy,\n        check: Effect.fn(\"GrantStore.check\")((capability) =>\n          Effect.suspend(() => {\n            const reply = replies[index++]\n            return reply !== undefined && reply !== \"deny\"\n              ? Effect.void\n              : Effect.fail(\n                permissionDenied(\n                  capability,\n                  reply === undefined ? \"permission reply script exhausted\" : \"permission request denied\"\n                )\n              )\n          })\n        ),\n        reply: Effect.fn(\"GrantStore.reply\")(() => Effect.fail(new GrantStoreError({ code: \"request_not_found\" }))),\n        list: Effect.fn(\"GrantStore.list\")(() => Effect.succeed([]))(),\n        grantEnvelope: Effect.fn(\"GrantStore.grantEnvelope\")(() => Effect.void)\n      })\n      return service\n    })\n  )\n"]}

package/docs/README.md

@@ -0,0 +1,162 @@
+---
+title: "@smthrs/kernel"
+description: "A capability kernel for Effect hosts: it decorates the filesystem, process, network, path, and Jujutsu service tags in place, so every side effect is checked against a grant store before it runs and refused with a typed error when nobody authorized it."
+---
+
+`@smthrs/kernel` puts a permission check in front of every side effect an
+[Effect](https://effect.website) program can reach. It wraps the five service
+tags a host provides, `FileSystem`, `Path`, `ChildProcessSpawner`, `HttpClient`,
+and `Jj`, with middleware that names the operation as a capability, asks a grant
+store whether it may proceed, and refuses it with a typed error when no rule
+allows it and nobody is there to ask. Four of those tags are Effect's own; `Jj`
+is the [Jujutsu](https://jj-vcs.github.io) repository port from
+[`@smthrs/jj`](/api/jj).
+
+## What it solves
+
+Running code you did not write, an agent's plan, a plugin, a generated build
+script, means every file write and every spawned process needs an answer to one
+question: did anyone authorize this. The usual way to enforce that answer is a
+second, protected service, and to tell every caller to use it. That breaks on
+the first dependency that never heard of your kernel and reaches for the
+ordinary `FileSystem` tag instead.
+
+This package decorates the ordinary tag in place. Once the layer is composed,
+the guarded implementation _is_ what the tag resolves to, so there is no
+unguarded one left to reach for. Code that calls `fs.readFileString` is checked
+without ever mentioning permission.
+
+A yes or no answer is not enough on its own, so the kernel also closes the gaps
+around it:
+
+- **Confinement.** A path is authorized as a canonical resource and the
+  operation runs through a pinned directory descriptor, so a symlink or a
+  rename between the decision and the call cannot redirect it.
+- **Containment.** A cancelled run signals its children, escalates to
+  `SIGKILL` on a deadline, and records each child in a durable ledger, so a
+  host that dies leaves orphan records its successor can reap.
+- **A ceiling that only narrows.** `CapabilitySet.attenuate` bounds what a
+  fiber may ask for, and no public operation widens it again.
+- **Grants that outlive the process.** A decision is written to a journal
+  before it takes effect, so a permission a person chose to remember is still
+  in force after a restart.
+
+## Install
+
+`@smthrs/kernel` is not on npm at 1.0.0-rc.0. Its source lives in the
+[smithers repository](https://github.com/smithersai/smithers), and
+[Installation](./installation.md) covers how to depend on it from a checkout,
+the import forms, and the three test subpaths.
+
+The package needs Node.js 26.4.0 or later. It carries no platform
+implementations of its own, so a composition that reaches a real machine also
+adds a bundle such as [`@smthrs/platform-node`](/api/platform-node).
+
+## Refuse an operation nobody authorized
+
+This program composes the kernel over `@smthrs/testing/TestHost`. Add
+`"@smthrs/testing": "workspace:*"` to the consuming package's devDependencies
+before running it. The policy allows reads under the workspace and says
+nothing about writes:
+
+```ts
+import { Capability, GrantStore, HostServices, Permission, Workspace } from "@smthrs/kernel"
+import * as TestHost from "@smthrs/testing/TestHost"
+import { Effect, FileSystem, Layer } from "effect"
+
+const rules = [
+  new Permission.Rule({
+    effect: "allow",
+    pattern: new Capability.CapabilityPattern({ action: "fs:read", resource: "/workspace/**" })
+  })
+]
+
+const guarded = HostServices.layer.pipe(
+  Layer.provide(Layer.orDie(GrantStore.layer({ attended: false, rules }))),
+  Layer.provideMerge(TestHost.layer({ files: { "/workspace/README.md": "# hello" } })),
+  Layer.provide(Workspace.layer("/workspace"))
+)
+
+/** Ordinary Effect code. Nothing here knows a kernel exists. */
+const program = Effect.gen(function*() {
+  const fs = yield* FileSystem.FileSystem
+  const readme = yield* fs.readFileString("/workspace/README.md")
+  yield* fs.writeFileString("/workspace/out.txt", readme)
+})
+
+Effect.runPromise(program.pipe(Effect.provide(guarded), Effect.scoped))
+```
+
+The read returns `"# hello"`. The write never reaches the filesystem. Effect
+fixes that method's error channel to `PlatformError`, so the kernel projects
+its refusal into one and keeps the structured original on the cause;
+`Permission.fromPlatformError` reads it back:
+
+```text
+{
+  _tag: '@smthrs/capability/PermissionRequired',
+  code: 'permission_required',
+  requestId: 'permission-1',
+  capability: { action: 'fs:write', resource: '/workspace/out.txt' },
+  tier: 'compensable',
+  meta: {}
+}
+```
+
+The `tier` says what re-running the refused operation would cost: a write
+inside the workspace is `compensable`, because the run can undo it from its own
+snapshot. See [effect tiers](/pkg/capability/concepts/effect-tiers) for the
+other two.
+
+`permission_required`, not `permission_denied`: no rule matched, silence is not
+consent, and this store has nobody to ask. Build the store with
+`attended: true` instead and the same write parks on a request an operator can
+answer, then resumes the operation it was authorized for. The
+[Quickstart](./quickstart.md) runs both halves.
+
+## How this fits with @smthrs/flows
+
+`@smthrs/kernel` is one package of the Smithers durable flow engine, which
+ships whole as [`@smthrs/flows`](/api/flows). Inside that engine the kernel is
+the layer between a flow's body and the machine:
+[`@smthrs/capability`](/api/capability) supplies the vocabulary it decides with,
+the [`@smthrs/platform-node`](/api/platform-node) family implements the ports it
+decorates, and [`@smthrs/engine`](/api/engine) runs steps over the guarded
+surface it composes. `@smthrs/flows` re-exports all of it as the `Kernel`
+namespace, and the durable Node runtime it builds is this composition at full
+size, so a program that already depends on the barrel does not install this
+package separately.
+
+Depend on `@smthrs/kernel` on its own when you are guarding a host of your own
+rather than running Smithers flows. Its only Smithers dependencies are the
+capability vocabulary, the journal, and the Jujutsu port, and its root entry
+point imports no Node built-ins, so the kernel runs wherever its host does.
+
+Further up, [`@smthrs/cli`](/api/cli) is the `smthrs` command line that
+everything here sits under. It finds the flows in a project, plans them, takes
+an approval, and runs them, and it builds its host through this kernel with a
+policy scoped to the project root, which is how a step that reaches outside
+that root gets stopped.
+
+## Where to go next
+
+- [Installation](./installation.md): runtime requirements, the import forms,
+  the three test subpaths, and the platform bundle you choose yourself.
+- [Quickstart](./quickstart.md): refuse a read on an unattended store, then
+  answer the same read on an attended one.
+- [Guard a host bundle](./guides/guard-a-host-bundle.md): the composition over
+  a real platform, in the right order, and the two mistakes that defeat it.
+- [Write a capability policy](./guides/write-a-capability-policy.md): the four
+  rulesets, the hard veto, and the resource each action names.
+- [Answer permission requests](./guides/answer-permission-requests.md): the
+  code on the other side of a parked request.
+- [Decoration in place](./concepts/decoration-in-place.md): why the kernel
+  guards the platform's own tags instead of publishing protected copies.
+- [How a grant decision is made](./concepts/grant-decisions.md): the ceiling,
+  the four rulesets, and the order they are consulted in.
+- [API reference](./api.md): every public export, its signature, and its
+  bounds.
+- [The kernel contract](./contract.md): what this package guarantees at a host
+  boundary, in one paragraph.
+- [Troubleshooting](./troubleshooting.md): each refusal this package raises,
+  what it means, and what to change.