@ravefox/space 0.2.1 → 0.3.0

package/node_modules/@commonlyai/seats/src/valet/grant.js

@@ -1,123 +0,0 @@
-/**
- * A grant says what one run may hold and do: which credentials reach its env,
- * and which tool calls it may make without asking, only after asking, or never.
- *
- *   {
- *     credentials: [{ name: 'OPENAI_API_KEY', from: 'env'|'file'|'resolver', ref?, inject? }],
- *     tools: { allow: [pattern], ask: [pattern], deny: [pattern] },
- *   }
- *
- * `from: 'env'` copies baseEnv[ref ?? name]; `from: 'file'` reads the absolute
- * path in `ref`; `from: 'resolver'` asks the host's resolveSecret(name, spec),
- * with `ref` as an opaque hint for it.
- *
- * `inject: true` keeps the value out of the run: its env gets a per-run proxy
- * token under the name instead, and a loopback provider proxy adds the real
- * key to outbound requests. Default false: the run holds the value.
- *
- * A tool pattern is `<kind>` or `<kind>:<title glob>`, where kind is one of
- * ACP's ToolKind values or `*`. `execute` matches every execute call;
- * `execute:git status*` matches execute calls whose title starts that way;
- * `*:*.env*` matches any kind by title. Globs know `*` and `?` only.
- *
- * The title is text the agent chose. A title-glob deny narrows what the agent
- * can do; a title-glob allow is only as strong as the agent's honesty about
- * its title, so prefer kind-level allows and put execute behind ask.
- *
- * Precedence is deny > ask > allow, and a call no rule names is denied.
- *
- * `network` rules are refused for now rather than accepted and ignored: a run
- * would believe it was fenced when nothing enforces the fence. TODO: egress
- * allowlist once a sandbox can enforce it.
- */
-
-export const TOOL_KINDS = Object.freeze(['read', 'edit', 'delete', 'move', 'search', 'execute', 'think', 'fetch', 'other']);
-export const CREDENTIAL_SOURCES = Object.freeze(['env', 'file', 'resolver']);
-const RULE_LISTS = ['deny', 'ask', 'allow']; // checked in this order: the precedence
-const VALIDATED = Symbol('validated grant');
-
-const ENV_NAME = /^[A-Z_][A-Z0-9_]*$/;
-// Names the run env is built from. A credential under one of these names would
-// overwrite the boundary itself (a granted HOME points back at the real login).
-const RESERVED_NAME = /^(?:HOME|PATH|TMPDIR|USER|LOGNAME|SHELL|PWD|LANG|LC_[A-Z0-9_]+|TERM|TZ|NO_COLOR|CI|SSL_CERT_FILE|SSL_CERT_DIR|XDG_[A-Z0-9_]+)$/;
-
-const fail = (message) => { throw new Error(`grant: ${message}`); };
-const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
-const refuseUnknownKeys = (value, allowed, where) => {
-  for (const key of Object.keys(value)) {
-    if (!allowed.includes(key)) fail(`unknown field ${where}${key}`);
-  }
-};
-
-const globToRegExp = (glob) => new RegExp(`^${glob.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[\\s\\S]*').replace(/\?/g, '[\\s\\S]')}$`);
-
-/** Parse once at validation so matching never re-reads a malformed pattern. */
-const parsePattern = (pattern, where) => {
-  if (typeof pattern !== 'string' || !pattern.trim()) fail(`${where} must be a non-empty string`);
-  const colon = pattern.indexOf(':');
-  const kind = colon === -1 ? pattern : pattern.slice(0, colon);
-  const title = colon === -1 ? null : pattern.slice(colon + 1);
-  if (kind !== '*' && !TOOL_KINDS.includes(kind)) fail(`${where} names unknown tool kind "${kind}"`);
-  if (title !== null && !title) fail(`${where} has an empty title glob`);
-  return Object.freeze({ pattern, kind, title: title === null ? null : globToRegExp(title) });
-};
-
-const validateCredential = (credential, index, seen) => {
-  const where = `credentials[${index}]`;
-  if (!isPlainObject(credential)) fail(`${where} must be an object`);
-  refuseUnknownKeys(credential, ['name', 'from', 'ref', 'inject'], `${where}.`);
-  const { name, from, ref, inject } = credential;
-  if (typeof name !== 'string' || !ENV_NAME.test(name)) fail(`${where}.name must be an ENV_NAME (A-Z, 0-9, _)`);
-  if (RESERVED_NAME.test(name)) fail(`${where}.name ${name} is reserved for the run env`);
-  if (seen.has(name)) fail(`${where}.name ${name} is granted twice`);
-  seen.add(name);
-  if (!CREDENTIAL_SOURCES.includes(from)) fail(`${where}.from must be one of ${CREDENTIAL_SOURCES.join(', ')}`);
-  if (ref !== undefined && (typeof ref !== 'string' || !ref)) fail(`${where}.ref must be a non-empty string`);
-  if (from === 'env' && ref !== undefined && !ENV_NAME.test(ref)) fail(`${where}.ref must be an ENV_NAME for from: env`);
-  if (from === 'file' && (ref === undefined || !ref.startsWith('/'))) fail(`${where}.ref must be an absolute path for from: file`);
-  if (inject !== undefined && typeof inject !== 'boolean') fail(`${where}.inject must be true or false`);
-  return Object.freeze({ name, from, ...(ref === undefined ? {} : { ref }), ...(inject ? { inject } : {}) });
-};
-
-/** Validate and freeze a grant. Throws on the first problem; never repairs one. */
-export const validateGrant = (grant) => {
-  if (grant && grant[VALIDATED]) return grant;
-  if (!isPlainObject(grant)) fail('must be an object');
-  if ('network' in grant) fail('network rules are not enforced yet; remove the field rather than rely on it');
-  refuseUnknownKeys(grant, ['credentials', 'tools'], '');
-  const credentials = grant.credentials ?? [];
-  if (!Array.isArray(credentials)) fail('credentials must be an array');
-  const seen = new Set();
-  const tools = grant.tools ?? {};
-  if (!isPlainObject(tools)) fail('tools must be an object');
-  refuseUnknownKeys(tools, RULE_LISTS, 'tools.');
-  const rules = {};
-  for (const list of RULE_LISTS) {
-    const patterns = tools[list] ?? [];
-    if (!Array.isArray(patterns)) fail(`tools.${list} must be an array`);
-    rules[list] = Object.freeze(patterns.map((pattern, i) => parsePattern(pattern, `tools.${list}[${i}]`)));
-  }
-  return Object.freeze({
-    [VALIDATED]: true,
-    credentials: Object.freeze(credentials.map((c, i) => validateCredential(c, i, seen))),
-    tools: Object.freeze(rules),
-  });
-};
-const matches = (parsed, kind, title) => (parsed.kind === '*' || parsed.kind === kind)
-  && (parsed.title === null || parsed.title.test(title));
-
-/**
- * Which rule decides this tool call. ACP makes `kind` optional and means
- * `other` when it is absent, so that is what an unknown or missing kind is.
- * Returns { decision: 'allow'|'ask'|'deny', rule: { list, pattern } }.
- */
-export const matchToolCall = (grant, toolCall = {}) => {
-  const valid = validateGrant(grant);
-  const kind = TOOL_KINDS.includes(toolCall?.kind) ? toolCall.kind : 'other';
-  const title = typeof toolCall?.title === 'string' ? toolCall.title : '';
-  for (const list of RULE_LISTS) {
-    const hit = valid.tools[list].find((parsed) => matches(parsed, kind, title));
-    if (hit) return { decision: list, rule: { list, pattern: hit.pattern } };
-  }
-  return { decision: 'deny', rule: { list: 'default', pattern: null } };
-};

package/node_modules/@commonlyai/seats/src/valet/permissions.js

@@ -1,213 +0,0 @@
-/**
- * Turn a grant into ctx.decidePermission: the answer to ACP's
- * session/request_permission, decided per tool call.
- *
- *   allow → the allow_once option
- *   deny  → the reject_once option, or cancelled when there is none
- *   ask   → approve({ toolCall, grantRule }) from the host. Only an answer
- *           that says who gave it decides:
- *           { approved: true | false, by: <user id>, role, decisionCardId? },
- *           with `role` an owner role. Anything else (a bare true, 'yes',
- *           {approved: 1}, an answer naming nobody, a throw, no answer in
- *           time) is a failed ask, and the policy's default, deny, decides.
- *           An answer whose role is `pod-member` decides nothing (ADR-033 D5):
- *           the call stays parked, and approve is called again with
- *           `refused: { by, role: 'pod-member', reason: 'not_owner' }` so the
- *           card can show why and wait for the owner.
- *
- * allow_always and reject_always are never chosen: either would be remembered
- * by the agent past this grant, so the next call would skip the check.
- * An allow rule with no allow_once option therefore denies.
- */
-import { traceOf } from '../trace/events.js';
-import { argsDigestOf, PARKED_CALL_ROLES, isUserId, policyActorId } from '../record/format.js';
-import { matchToolCall, validateGrant } from './grant.js';
-
-export const DEFAULT_APPROVE_TIMEOUT_MS = 5 * 60 * 1000;
-// An approver that keeps handing back pod-member answers is broken; after this
-// many the ask fails, and the policy's default decides, as for any broken approver.
-export const MAX_REFUSED_ANSWERS = 10;
-
-const optionOfKind = (options, kind) => (Array.isArray(options) ? options : [])
-  .find((option) => option && option.kind === kind && typeof option.optionId === 'string');
-
-const allowAnswer = (options) => {
-  const option = optionOfKind(options, 'allow_once');
-  return option ? { outcome: 'selected', optionId: option.optionId, kind: option.kind } : null;
-};
-const denyAnswer = (options) => {
-  const option = optionOfKind(options, 'reject_once');
-  return option ? { outcome: 'selected', optionId: option.optionId, kind: option.kind } : { outcome: 'cancelled' };
-};
-
-const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
-const isText = (value) => typeof value === 'string' && value.length > 0;
-
-// The roles a person can answer a parked call as; `policy` is not a person.
-const ANSWER_ROLES = PARKED_CALL_ROLES.filter((role) => role !== 'policy');
-
-/**
- * What an approver's answer says. It approves or rejects only when it is an
- * object whose `approved` is exactly true or false and that names a user id
- * and an owner role. Any other answer approves nothing: it is a failed ask,
- * so the record never carries a decision nobody can be held to.
- */
-const readAnswer = (answer) => {
-  if (!isPlainObject(answer) || typeof answer.approved !== 'boolean') return { verdict: 'failed' };
-  if (!isUserId(answer.by) || !ANSWER_ROLES.includes(answer.role)) return { verdict: 'failed' };
-  return {
-    verdict: answer.approved ? 'approved' : 'rejected',
-    by: answer.by,
-    role: answer.role,
-    ...(isText(answer.decisionCardId) ? { decisionCardId: answer.decisionCardId } : {}),
-  };
-};
-
-const isPodMemberAnswer = (answer) => isPlainObject(answer) && answer.role === 'pod-member';
-
-/**
- * Wait for the host's approval, bounded. Resolves { verdict, by?, role?,
- * decisionCardId? }, verdict 'approved' | 'rejected' | 'timed_out' | 'failed'
- * | 'aborted'; never rejects, so a broken approver becomes a denial rather
- * than a hung or crashed turn.
- */
-const awaitApproval = (approve, input, { timeoutMs, signal }) => new Promise((done) => {
-  if (typeof approve !== 'function') { done({ verdict: 'failed' }); return; }
-  if (signal?.aborted) { done({ verdict: 'aborted' }); return; }
-  let finished = false;
-  const finish = (verdict) => {
-    if (finished) return;
-    finished = true;
-    clearTimeout(timer);
-    signal?.removeEventListener?.('abort', onAbort);
-    done(verdict);
-  };
-  const onAbort = () => finish({ verdict: 'aborted' });
-  const timer = setTimeout(() => finish({ verdict: 'timed_out' }), timeoutMs);
-  signal?.addEventListener?.('abort', onAbort, { once: true });
-  let refusals = 0;
-  const ask = (current) => Promise.resolve()
-    .then(() => approve(current))
-    .then((answer) => {
-      if (finished) return;
-      if (!isPodMemberAnswer(answer)) { finish(readAnswer(answer)); return; }
-      // A pod member may not decide a parked call: the call stays parked and
-      // the owner is asked again, with the refusal, inside the same timeout.
-      refusals += 1;
-      if (refusals > MAX_REFUSED_ANSWERS) { finish({ verdict: 'failed' }); return; }
-      const refused = { by: isUserId(answer.by) ? answer.by : null, role: 'pod-member', reason: 'not_owner' };
-      setTimeout(() => { if (!finished) ask({ ...input, refused }); }, 0);
-    }, () => finish({ verdict: 'failed' }));
-  ask(input);
-});
-
-/**
- * Who decided an ask, for the record. A person who answered is named by the
- * approver; anything else (no answer in time, an answer naming nobody, a
- * broken approver, a cancelled run) means the policy's default decided.
- * Rule-decided calls carry no decidedBy here; the record writer fills in
- * "policy" for any decision whose rule list is not `ask`.
- */
-const decider = (approval) => {
-  if (approval.verdict === 'approved' || approval.verdict === 'rejected') {
-    return {
-      decidedBy: approval.by,
-      decidedByRole: approval.role,
-      ...(approval.decisionCardId ? { decisionCardId: approval.decisionCardId } : {}),
-    };
-  }
-  return { decidedBy: 'policy', decidedByRole: 'policy' };
-};
-
-const isAsker = (value) => isPlainObject(value) && isUserId(value.id) && PARKED_CALL_ROLES.includes(value.role);
-
-/**
- * Who an ask goes to, for permission.requested. `askedOf` is {id, role} or
- * ({toolCall, grantRule}) => {id, role, decisionCardId?}. A call a
- * rule decides is asked of the grant's policy. A function that throws or
- * answers malformed is recorded as asked of the policy too: the record does
- * not name a person it cannot vouch for.
- */
-const askOf = (askedOf, input, policy) => {
-  if (input.grantRule?.list !== 'ask') return policy;
-  let answer = askedOf;
-  if (typeof askedOf === 'function') {
-    try { answer = askedOf(input); } catch { answer = null; }
-  }
-  if (!isAsker(answer)) return policy;
-  return {
-    id: answer.id,
-    role: answer.role,
-    ...(isText(answer.decisionCardId) ? { decisionCardId: answer.decisionCardId } : {}),
-  };
-};
-
-/**
- * createPermissionPolicy(grant, { approve?, trace?, approveTimeoutMs?, signal?, grantId?, askedOf? })
- *   → (request) => Promise<{outcome:'selected', optionId} | {outcome:'cancelled'}>
- *
- * `signal` is the run's AbortSignal: a cancelled run answers a pending ask
- * with cancelled, which is what ACP asks of a client after session/cancel.
- * `grantId` is recorded on each decision, to tie it to its grant.issued.
- * With `askedOf` (above), each request is recorded first as
- * permission.requested: the question (the tool call's title), who it is
- * asked of, and the card it rides on. The approver receives that card id.
- * When the tool call carries `rawInput`, both entries carry its argsDigest.
- * Given a `trace`, the returned function has `recordsPermissions === true`.
- */
-export const createPermissionPolicy = (grant, {
-  approve, trace, approveTimeoutMs = DEFAULT_APPROVE_TIMEOUT_MS, signal, grantId, askedOf,
-} = {}) => {
-  const valid = validateGrant(grant);
-  const hook = traceOf({ trace });
-  if (askedOf !== undefined && typeof askedOf !== 'function' && !isAsker(askedOf)) {
-    throw new Error('askedOf must be {id: <user id>, role: <decidedByRole>} or a function returning one');
-  }
-  const policy = { id: policyActorId(grantId), role: 'policy' };
-  const decide = async (request = {}) => {
-    const toolCall = request?.toolCall || {};
-    const options = request?.options;
-    const { decision, rule } = matchToolCall(valid, toolCall);
-    const toolCallId = typeof toolCall.toolCallId === 'string' ? toolCall.toolCallId : null;
-    const argsDigest = argsDigestOf(toolCall.rawInput);
-    let asker = null;
-    if (askedOf !== undefined) {
-      asker = askOf(askedOf, { toolCall, grantRule: rule }, policy);
-      const fallback = `${isText(toolCall.kind) ? toolCall.kind : 'tool'} call`;
-      hook.emit('permission.requested', {
-        toolCallId,
-        options: (Array.isArray(options) ? options : []).filter(isPlainObject).map(({ optionId, kind }) => ({ optionId, kind })),
-        question: isText(toolCall.title) ? toolCall.title : fallback,
-        askedOf: { id: asker.id, role: asker.role },
-        ...(grantId ? { grantId } : {}),
-        ...(asker.decisionCardId ? { decisionCardId: asker.decisionCardId } : {}),
-        ...(argsDigest ? { argsDigest } : {}),
-      });
-    }
-    let approval;
-    let answer;
-    if (decision === 'ask') {
-      const input = { toolCall, grantRule: rule, ...(asker?.decisionCardId ? { decisionCardId: asker.decisionCardId } : {}) };
-      approval = await awaitApproval(approve, input, { timeoutMs: approveTimeoutMs, signal });
-      if (approval.verdict === 'aborted') answer = { outcome: 'cancelled' };
-      else answer = approval.verdict === 'approved' ? allowAnswer(options) : null;
-    } else if (decision === 'allow') {
-      answer = allowAnswer(options);
-    }
-    if (!answer) answer = denyAnswer(options);
-    hook.emit('permission.decided', {
-      outcome: answer.outcome,
-      ...(answer.optionId ? { optionId: answer.optionId, kind: answer.kind } : {}),
-      toolCallId,
-      rule,
-      ...(approval ? { approval: approval.verdict, ...decider(approval) } : {}),
-      ...(grantId ? { grantId } : {}),
-      ...(argsDigest ? { argsDigest } : {}),
-    });
-    return answer.outcome === 'selected' ? { outcome: 'selected', optionId: answer.optionId } : { outcome: 'cancelled' };
-  };
-  // With a trace this writes both permission entries itself, so an adapter
-  // handed it as ctx.decidePermission must not write them again.
-  if (trace) Object.defineProperty(decide, 'recordsPermissions', { value: true });
-  return decide;
-};