@melra/policy-core 0.3.0-alpha.10

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,78 @@
+# @melra/policy-core
+
+Policy evaluation and scoped approval primitives for
+[MELRA](https://github.com/XAGI-Lab/melra). Decides allow, deny, or confirm for
+a typed operation before any adapter runs, and issues and validates the
+task-scoped approval challenges that gate mutations.
+
+```bash
+npm install @melra/policy-core
+```
+
+```ts
+import { createDefaultPolicy, evaluatePolicy } from "@melra/policy-core";
+
+const policy = createDefaultPolicy(process.cwd());
+const { decision, challenge } = evaluatePolicy(taskId, request, policy);
+```
+
+An `allow` runs. A `confirm` returns a `challenge` whose exact phrase must be
+echoed back before execution, bound to the task and to a digest of the operation
+— so a plan cannot be swapped for a different action after approval. A `deny`
+never reaches a runtime.
+
+## Defaults worth knowing
+
+- A non-empty `constraints` array is denied. Freeform prose is not enforceable,
+  so the honest answer is to refuse rather than pretend it was applied.
+- Any non-`read` effect with no `requiredEvidence` is denied. A mutation nobody
+  can check is not a mutation worth running.
+- Terminal commands must be allowlisted by basename. Shell interpreters and
+  `sudo`/`su` are denied unconditionally. `git` counts as a read only for a small
+  read-only subcommand set; `npm`, `npx`, and `pnpm` are high-risk mutations.
+- Browser destinations default to `allowedDomains: ["*"]` with localhost allowed,
+  because the allowlist is a narrowing control, not the safety boundary — the
+  browser runtime independently blocks private and metadata destinations.
+- `classifyOperation` is the single place effect and risk are decided. An action
+  that is not classified there is mis-classified, not unclassified.
+
+## Capability grants
+
+`policy.capabilities` is authority; everything above is rules. It is empty by
+default and changes nothing when it is. A non-empty list is a closed world,
+checked before any allowlist — because an allowlist describes what a grant
+holder may do, not whether they hold one.
+
+```ts
+import { createDefaultPolicy, type LocalPolicy } from "@melra/policy-core";
+
+const policy: LocalPolicy = {
+  ...createDefaultPolicy(process.cwd()),
+  capabilities: [
+    {
+      id: "build-writes",
+      capability: "file.*",
+      effects: ["read", "mutate"],
+      target: "*/build/*",
+      principal: "agent:ci-runner",
+    },
+  ],
+};
+```
+
+`capability` and `target` are matched against what `classifyOperation` reported,
+with `*` standing for any run of characters. `principal` is matched against
+`request.identity.principal` written `kind:id`; a request that declares no
+identity is `agent:local`. An effect with no matching grant is denied
+`capability_not_granted`, an expired one `capability_expired`, and one issued
+against a superseded `policyVersion` is refused rather than reinterpreted under
+rules it was not written for.
+
+`unhinged: true` short-circuits evaluation to `allow` — but only after the
+caller's own `forbiddenEffects` and `constraints` are honoured, because those are
+the caller bounding its own task rather than a guardrail MELRA imposes.
+
+Requires Node.js 22 or newer. Full documentation:
+[github.com/XAGI-Lab/melra](https://github.com/XAGI-Lab/melra)
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import type { ApprovalChallenge, ApprovalResponse, CapabilityGrant, CapabilityTrait, Effect, EvidencePredicate, Identity, Operation, PolicyDecision, Risk, TaskRequest } from "@melra/protocol";
+export interface LocalPolicy {
+    version: string;
+    workspaceRoot: string;
+    allowedCommands: string[];
+    allowedDomains: string[];
+    allowLocalhost: boolean;
+    /**
+     * What to do with a window a page opens by itself.
+     *
+     * `"block"` closes it and reports it on the action that provoked it, which is
+     * the honest default for an unattended agent: a popup nobody asked for is the
+     * page deciding what the caller looks at next. `"allow"` keeps it as an
+     * addressable tab. Either way it is reported — this governs whether it stays,
+     * not whether the caller is told. `assertSafeUrl` still governs where it may
+     * load from.
+     */
+    popups: "allow" | "block";
+    mutations: "deny" | "confirm";
+    approvalTtlMs: number;
+    maxFileBytes: number;
+    /**
+     * How long unreachable memory rows are kept before compaction reclaims them,
+     * and an optional hard ceiling on live memories per scope.
+     *
+     * `maxPerScope: 0` means no ceiling, which is the default: evicting a live
+     * memory throws away something the caller stored and can still read, so it
+     * is opt-in. Expired and superseded rows are reclaimed regardless — no read
+     * path can return them.
+     */
+    memoryRetention: {
+        maxAgeDays: number;
+        maxPerScope: number;
+    };
+    /**
+     * Traits an operation may not carry. Empty by default — the shipped policy
+     * still confirms every mutation, so nothing runs unattended, and denying
+     * installs or the network outright is a choice only some installs want.
+     *
+     * `["package-install"]` lets a task run `npm test` but not `npm install`,
+     * which `allowedCommands` cannot express because it matches on the basename.
+     * `["network"]` refuses anything that reaches another host, browsing
+     * included.
+     */
+    deniedTraits: CapabilityTrait[];
+    /**
+     * Bounded authority the operator has issued, matched against the effect and
+     * the immediate principal before any allowlist is consulted.
+     *
+     * Empty by default, which means no capability narrowing: policy behaves as it
+     * always has. A non-empty list is a closed world — an effect with no matching
+     * grant is denied with `capability_not_granted`. This is how a caller ends up
+     * holding authority over one directory rather than over the whole workspace.
+     */
+    capabilities: CapabilityGrant[];
+    /**
+     * Stops a task from re-running an operation whose target keeps failing.
+     *
+     * A retry inside one task only covers a transient blip; nothing carried the
+     * knowledge that the last three tasks against this same file, host, or command
+     * all failed, so a workflow would keep spending its budget rediscovering it.
+     * After `threshold` consecutive failures against one target, the next task
+     * touching it fails immediately with `circuit_open:<target>` until
+     * `cooldownMs` has passed; the first task after the cooldown is the trial, and
+     * one success clears the count. `threshold: 0` switches it off.
+     */
+    circuitBreaker: {
+        threshold: number;
+        cooldownMs: number;
+    };
+    /**
+     * Switches off every guardrail this policy exists to apply: allowlists,
+     * evidence requirements, approval challenges, and — through the runtimes
+     * constructed from this policy — workspace confinement and the browser's
+     * private-destination block.
+     *
+     * Off unless the operator asks for it twice, once through `MELRA_UNHINGED=1`
+     * or `--unhinged` and once by accepting the banner the CLI prints. Nothing
+     * derives it from another setting.
+     */
+    unhinged: boolean;
+}
+export interface PolicyEvaluation {
+    decision: PolicyDecision;
+    challenge?: ApprovalChallenge;
+}
+export declare function normalizeCommandName(command: string): string;
+/**
+ * What an operation does beyond changing local state, named so a policy can
+ * refuse it.
+ *
+ * `effect` answers "does this write" and `risk` answers "how badly could it
+ * go", but neither distinguishes `npm test` from `npm install left-pad`, and
+ * `allowedCommands` matches on the basename so it cannot either. An operator
+ * who wants a package manager for its scripts but not for fetching code from
+ * a registry had no way to say so. Traits are that missing axis.
+ *
+ * - `package-install` — resolves and installs third-party code, which is the
+ *   one terminal action that can add executable content the operator never
+ *   reviewed.
+ * - `network` — reaches a host outside this machine. Browser navigation
+ *   carries it too, because it is true: `deniedTraits: ["network"]` means no
+ *   network at all, not "no network except the browser".
+ */
+export type { CapabilityTrait } from "@melra/protocol";
+/**
+ * Classify a terminal command by what it does, not just by its name.
+ *
+ * Exported because the accurate answer is worth having outside policy — the
+ * CLI's `policy test` prints it, and it is the only place `npm ls` and `npm
+ * install` are told apart.
+ */
+export declare function classifyCommand(command: string, args: readonly string[]): {
+    read: boolean;
+    traits: CapabilityTrait[];
+};
+export declare function createDefaultPolicy(workspaceRoot: string): LocalPolicy;
+export declare function loadPolicy(path: string | undefined, workspaceRoot: string): Promise<LocalPolicy>;
+export declare function classifyOperation(operation: Operation): {
+    effect: Effect;
+    risk: Risk;
+    capability: string;
+    target: string;
+    traits: CapabilityTrait[];
+};
+/**
+ * Evidence a mutation must satisfy when the caller declared none.
+ *
+ * Mutations still require evidence — that rule is the product's verification
+ * thesis and is not relaxed here. What changed is the failure mode: previously a
+ * caller who omitted `requiredEvidence` got a flat `mutation_requires_evidence`
+ * deny and had to guess the right predicate, so most callers simply gave up. Now
+ * the obvious post-condition is derived from the operation itself, and the task
+ * is held to it exactly as if the caller had written it.
+ *
+ * Returns `[]` when no post-condition is derivable from the request alone (for
+ * example a `terminal run`, whose effect depends on the command). Those still
+ * deny, because a mutation nobody can check is precisely what should not run
+ * unattended.
+ */
+export declare function defaultEvidenceFor(operation: Operation): EvidencePredicate[];
+/**
+ * Why the issued capabilities do not cover this effect, or `undefined` if they
+ * do. An empty grant list is not a closed world — it means the operator has not
+ * issued grants at all, and the rest of policy decides on its own.
+ */
+export declare function capabilityRefusal(classified: {
+    effect: Effect;
+    capability: string;
+    target: string;
+}, identity: Identity, policy: LocalPolicy): string | undefined;
+export declare function evaluatePolicy(taskId: string, request: TaskRequest, policy: LocalPolicy): PolicyEvaluation;
+export declare function digestOperation(taskId: string, operation: Operation): string;
+export declare function validateApproval(challenge: ApprovalChallenge | undefined, response: ApprovalResponse | undefined): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}