agy-worker-mcp 0.3.1

package/dist/policy/rules.d.ts

@@ -0,0 +1,138 @@
+import type { ParsedRule, RuleVerb } from '../contract/types.js';
+/**
+ * Permission rule strings, in agy's own vocabulary (§12):
+ * `command(...)`, `read_file(...)`, `write_file(...)`, `fetch(...)`, `url(...)`,
+ * `mcp(...)`, `browser(...)`. Matching is strict and non-regex by default;
+ * `regex:` opts in. Wildcards `command(*)` and `read_file(/)` are recognized.
+ */
+export declare const RULE_VERBS: readonly RuleVerb[];
+/** @throws {import('../contract/errors.js').ValidationError} carrying `allowed_verbs`. */
+export declare function parseRule(raw: string): ParsedRule;
+/** Parses every rule; the first bad one throws, so a caller never gets a half set. */
+export declare function parseRules(raws: string[]): ParsedRule[];
+/** Same as {@link parseRules}, but a malformed entry is dropped instead of thrown. */
+export declare function parseRulesLenient(raws: string[]): ParsedRule[];
+/** What a rule is being matched against. */
+export interface RuleSubject {
+    verb: RuleVerb;
+    /** Command line, absolute path, or URL depending on the verb. */
+    value: string;
+}
+/** `**` -> any depth, `*` -> one path segment / token, everything else literal. */
+export declare function globToRegex(pattern: string): RegExp;
+/**
+ * Environment variables that must never be assigned inline or via env/export.
+ * Rationale:
+ * - PATH: Binary resolution hijacking by prepending untrusted directories.
+ * - LD_*, DYLD_*: Dynamic linker hijacking (preloading arbitrary shared libraries on Linux / macOS).
+ * - NODE_OPTIONS: Node.js runtime flag / hook injection (e.g. --require, --inspect).
+ * - BASH_ENV, ENV: Startup script execution on shell invocation.
+ * - GIT_DIR, GIT_WORK_TREE: Redirects git repository / working tree outside the workspace.
+ * - GIT_SSH, GIT_SSH_COMMAND: Arbitrary binary execution during git network operations.
+ * - GIT_CONFIG*, GIT_EXEC_PATH: Git config override or custom hook/binary injection.
+ * - PYTHONSTARTUP, PYTHONPATH: Arbitrary code execution or library hijacking at Python startup.
+ * - PERL5OPT, RUBYOPT: Option/code injection at Perl/Ruby interpreter startup.
+ * - JAVA_TOOL_OPTIONS, _JAVA_OPTIONS: JVM argument injection (e.g. -javaagent).
+ */
+export declare const DENIED_ENV_PATTERNS: readonly (string | RegExp)[];
+export declare function isDeniedEnvVar(name: string): boolean;
+/** Recognize -c inside short flag clusters, e.g. -c, -lc, -ec, -xc, -lec */
+export declare function isShellCFlag(token: string): boolean;
+/** Check if head token contains backslash, $, quote, or non-ASCII */
+export declare function headTokenIsObfuscated(token: string): boolean;
+/** Tokenizer that preserves quote characters in tokens for obfuscation detection */
+export declare function tokenizeCommandRaw(cmd: string): string[];
+/** Check if rm invocation has both recursive and force flags */
+export declare function isRmRfTokens(tokens: string[]): boolean;
+/** Keys that must not be written to in git config */
+export declare function isDeniedGitConfigKey(key: string): boolean;
+/** Check if git command uses forbidden global options or writes to sensitive config keys */
+export declare function checkGitSegment(tokens: string[]): {
+    denied: boolean;
+    reason?: string;
+};
+export declare function isDeniedFindSegment(tokens: string[]): boolean;
+export declare function extractXargsTarget(tokens: string[]): string[] | null;
+/** A minimal shell-aware tokenizer: `'...'`/`"..."` groups survive as one token, quotes stripped. */
+export declare function tokenizeCommand(cmd: string): string[];
+export interface EnvPrefixResult {
+    assignments: {
+        name: string;
+        value: string;
+    }[];
+    deniedVar: string | null;
+    isExport: boolean;
+    isAssignmentOnly: boolean;
+    remainingTokens: string[];
+}
+export declare function stripEnvPrefixTokens(tokens: string[]): EnvPrefixResult;
+/**
+ * Split command line by delimiters `&&`, `||`, `;`, `|` outside quotes.
+ * Returns `null` on syntax error (unbalanced quotes, heredoc `<<`).
+ */
+export declare function splitChainSegments(cmd: string): string[] | null;
+/**
+ * Extract command substitutions `$(...)` and ``` `...` ``` outside single quotes.
+ * Returns `null` on unbalanced substitution or quote syntax error.
+ */
+export declare function extractCommandSubstitutions(segment: string): {
+    sanitized: string;
+    substitutions: string[];
+} | null;
+/**
+ * Deny-only matcher. Unlike {@link matchRule} (used for allow-list matching,
+ * where anchoring the pattern at the command's first token is intentional
+ * precision — an allow rule must never widen because it happens to appear
+ * mid-command), this scans every token window of the (tokenized, quote-aware)
+ * command line and unwraps one layer of a shell/exec wrapper before giving up,
+ * so `sh -c 'git push origin main'`, `/usr/bin/curl ...` and `env curl ...`
+ * cannot slip past a `command(git push)` / `command(curl)` HARD_DENY entry
+ * (finding 15).
+ */
+export declare function matchRuleForDenial(rule: ParsedRule, subject: RuleSubject): boolean;
+/** Deny-list form of {@link firstMatch}, using {@link matchRuleForDenial}. */
+export declare function firstMatchForDenial(rules: ParsedRule[], subject: RuleSubject): ParsedRule | null;
+/**
+ * Bare glob matching against a filesystem path — no `verb(pattern)` rule
+ * envelope. Used for `Ceiling.read_roots`, which is a list of glob patterns,
+ * not permission rules, so it
+ * has no verb to check. Same `**`/`*` semantics `matchRule` already uses for
+ * `read_file`/`write_file` patterns (`globToRegex`) — exported here instead of
+ * a second implementation living in `policy/ceiling.ts`.
+ */
+export declare function matchesPathGlob(pattern: string, value: string): boolean;
+export declare function matchRule(rule: ParsedRule, subject: RuleSubject): boolean;
+export interface CommandPolicyResult {
+    allowed: boolean;
+    stage: 'profile_allowlist' | 'deny_list' | 'default';
+    matchedRule: string | null;
+    requiredRule: string | null;
+    reason?: string;
+}
+export declare function evaluateCommandPolicy(commandLine: string, allowRules: ParsedRule[], denyRules: ParsedRule[], depth?: number): CommandPolicyResult;
+/** First matching rule in order, or null. Deny lists are scanned before allow lists. */
+export declare function firstMatch(rules: ParsedRule[], subject: RuleSubject): ParsedRule | null;
+export interface IntersectResult {
+    /** Requested entries the ceiling covers. */
+    allowed: string[];
+    /** Requested entries the ceiling refuses, reported back to the caller. */
+    rejected: string[];
+}
+/**
+ * Intersect a client's requested allow list with a profile ceiling.
+ *
+ * A request is kept only when some ceiling rule of the same verb covers it — an
+ * unrelated rule can never let something new through. This is the single place
+ * that stops a client widening the server's hard limit (see docs/permissions.md).
+ *
+ * "Covers" is checked by matching the *ceiling* rule against the *requested*
+ * rule's own pattern treated as a subject value — the requested rule must be at
+ * least as narrow as something the ceiling already allows.
+ */
+export declare function intersectAllow(requested: string[], ceiling: string[]): IntersectResult;
+/**
+ * The narrowest rule string that would have permitted `subject`.
+ * Surfaced as `required_rule` so the calling agent can retry without a round trip.
+ */
+export declare function requiredRuleFor(subject: RuleSubject): string;
+//# sourceMappingURL=rules.d.ts.map

package/dist/policy/rules.d.ts.map

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