@kybernesis/arp-scope-catalog 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kybernesis AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @kybernesis/arp-scope-catalog
+
+The ARP scope catalog v1 — 50 scope templates authored as YAML — plus the Handlebars→Cedar compiler that turns a selection of scopes into a compiled policy set.
+
+Humans never write Cedar. They pick scopes from this catalog, and a compiler produces the policy. This package is both the source of truth (the `scopes/*.yaml` files) and the tooling (the loader + compiler) for doing that.
+
+## Install
+
+```bash
+pnpm add @kybernesis/arp-scope-catalog
+```
+
+## Usage
+
+### Load the catalog + compile a single scope
+
+```ts
+import { loadScopesFromDirectory, compileScope } from '@kybernesis/arp-scope-catalog';
+
+const catalog = loadScopesFromDirectory('./node_modules/@kybernesis/arp-scope-catalog/scopes');
+
+const permitCalendar = compileScope({
+  scope: catalog.find((s) => s.id === 'calendar.availability.read')!,
+  audienceDid: 'did:web:ghost.agent',
+  params: { days_ahead: 14 },
+});
+
+console.log(permitCalendar);
+// permit (
+//   principal == Agent::"did:web:ghost.agent",
+//   action == Action::"check_availability",
+//   resource == Calendar::"primary"
+// ) when { context.query_window_days <= 14 };
+// forbid ( ... ) when { action != Action::"check_availability" };
+```
+
+### Compile a bundle of scopes
+
+```ts
+import { compileBundle, BUNDLES, findBundle } from '@kybernesis/arp-scope-catalog';
+
+const bundle = findBundle('bundle.scheduling_assistant.v1')!;
+
+const compiled = compileBundle({
+  scopeIds: bundle.scopes.map((s) => s.id),
+  paramsMap: {
+    'calendar.availability.read': { days_ahead: 14 },
+    'calendar.events.propose': { max_attendees: 10, max_duration_min: 60 },
+    'contacts.search': { attribute_allowlist: ['name', 'email'] },
+  },
+  audienceDid: 'did:web:ghost.agent',
+  catalog,
+});
+
+console.log(compiled.policies);          // string[] — one compiled policy per scope
+console.log(compiled.obligations);       // Obligation[] — aggregated post-allow requirements
+console.log(compiled.expandedScopeIds);  // string[] — including implied scopes
+```
+
+The bundle compiler:
+- Transitively expands `implies` relations so the consent UI doesn't have to ask for prerequisites twice.
+- Detects `conflicts_with` pairs and throws before compilation.
+- Inherits parameters along implication edges (e.g., a `project_id` on `files.project.files.read` propagates to its implied `files.project.files.list`).
+- Concatenates `obligations_forced` across the expanded set.
+
+## The 50 scopes
+
+Authored as one YAML file per scope under `scopes/`. The `generated/manifest.json` file is the public manifest served at `/.well-known/scope-catalog.json` — see `ARP-scope-catalog-v1.md` for the full list.
+
+Scope categories: identity, calendar, messaging, files, contacts, tasks, notes, payments, work, credentials, tools, delegation.
+
+Risk tiers: low, medium, high, critical (see §2 of the catalog doc for default obligations by tier).
+
+## Phase
+
+Shipped as part of Phase 1. See [`docs/ARP-phase-0-roadmap.md`](../../docs/ARP-phase-0-roadmap.md).
+
+## License
+
+MIT.

package/dist/index.cjs

@@ -0,0 +1,518 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var yaml = require('yaml');
+var arpSpec = require('@kybernesis/arp-spec');
+var crypto = require('crypto');
+var Handlebars = require('handlebars');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Handlebars__default = /*#__PURE__*/_interopDefault(Handlebars);
+
+// src/loader.ts
+var ScopeLoadError = class extends Error {
+  file;
+  issues;
+  constructor(message, opts) {
+    super(message);
+    this.name = "ScopeLoadError";
+    if (opts?.file !== void 0) this.file = opts.file;
+    if (opts?.issues !== void 0) this.issues = opts.issues;
+  }
+};
+function loadScopeFile(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, "utf8");
+  } catch (e) {
+    throw new ScopeLoadError(`cannot read ${filePath}: ${e.message}`, {
+      file: filePath
+    });
+  }
+  let parsed;
+  try {
+    parsed = yaml.parse(raw);
+  } catch (e) {
+    throw new ScopeLoadError(`invalid YAML in ${filePath}: ${e.message}`, {
+      file: filePath
+    });
+  }
+  const result = arpSpec.ScopeTemplateSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new ScopeLoadError(`scope ${filePath} failed schema validation`, {
+      file: filePath,
+      issues: result.error.issues
+    });
+  }
+  return result.data;
+}
+function loadScopesFromDirectory(scopesDir) {
+  const st = fs.statSync(scopesDir);
+  if (!st.isDirectory()) {
+    throw new ScopeLoadError(`${scopesDir} is not a directory`);
+  }
+  const files = fs.readdirSync(scopesDir).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")).sort();
+  const seen = /* @__PURE__ */ new Set();
+  const scopes = [];
+  for (const file of files) {
+    const full = path.resolve(scopesDir, file);
+    const scope = loadScopeFile(full);
+    const expected = `${scope.id}.yaml`;
+    if (file !== expected && !(file === `${scope.id}.yml`)) {
+      throw new ScopeLoadError(
+        `filename ${file} does not match scope id ${scope.id} (expected ${expected})`,
+        { file: full }
+      );
+    }
+    if (seen.has(scope.id)) {
+      throw new ScopeLoadError(`duplicate scope id ${scope.id}`, { file: full });
+    }
+    seen.add(scope.id);
+    scopes.push(scope);
+  }
+  scopes.sort((a, b) => a.id.localeCompare(b.id));
+  return scopes;
+}
+function canonicalize(value) {
+  if (value === null) return "null";
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new Error("canonicalize: non-finite numbers are not allowed");
+  }
+  if (typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalize).join(",")}]`;
+  }
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`);
+  return `{${parts.join(",")}}`;
+}
+function sha256Hex(input) {
+  return crypto.createHash("sha256").update(input, "utf8").digest("hex");
+}
+function buildCatalogManifest(scopes, options = {}) {
+  const sorted = [...scopes].sort((a, b) => a.id.localeCompare(b.id));
+  const canonical = canonicalize(sorted);
+  const checksum = `sha256:${sha256Hex(canonical)}`;
+  const manifest = {
+    version: options.version ?? "v1",
+    updated_at: options.updatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    scope_count: sorted.length,
+    checksum,
+    scopes: sorted
+  };
+  const parsed = arpSpec.ScopeCatalogManifestSchema.parse(manifest);
+  return parsed;
+}
+var ScopeCompileError = class extends Error {
+  scopeId;
+  parameter;
+  constructor(message, opts) {
+    super(message);
+    this.name = "ScopeCompileError";
+    if (opts?.scopeId !== void 0) this.scopeId = opts.scopeId;
+    if (opts?.parameter !== void 0) this.parameter = opts.parameter;
+  }
+};
+function parseRangeValidation(validation) {
+  const match = /^(-?\d+(?:\.\d+)?)\.\.(-?\d+(?:\.\d+)?)$/.exec(validation);
+  if (!match) return null;
+  return { min: Number(match[1]), max: Number(match[2]) };
+}
+function coerceToNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  return null;
+}
+function validateParameter(scopeId, def, initial) {
+  let value = initial;
+  const present = value !== void 0 && value !== null;
+  if (!present) {
+    if (def.default !== void 0) {
+      value = def.default;
+    } else if (def.required) {
+      throw new ScopeCompileError(
+        `missing required parameter '${def.name}' for scope ${scopeId}`,
+        { scopeId, parameter: def.name }
+      );
+    } else {
+      return void 0;
+    }
+  }
+  switch (def.type) {
+    case "Integer": {
+      const n = coerceToNumber(value);
+      if (n === null || !Number.isInteger(n)) {
+        throw new ScopeCompileError(
+          `parameter '${def.name}' must be an integer`,
+          { scopeId, parameter: def.name }
+        );
+      }
+      if (typeof def.validation === "string") {
+        const range = parseRangeValidation(def.validation);
+        if (range && (n < range.min || n > range.max)) {
+          throw new ScopeCompileError(
+            `parameter '${def.name}'=${n} out of range ${def.validation}`,
+            { scopeId, parameter: def.name }
+          );
+        }
+      }
+      return n;
+    }
+    case "Decimal": {
+      const n = coerceToNumber(value);
+      if (n === null) {
+        throw new ScopeCompileError(
+          `parameter '${def.name}' must be a number`,
+          { scopeId, parameter: def.name }
+        );
+      }
+      if (typeof def.validation === "string") {
+        const range = parseRangeValidation(def.validation);
+        if (range && (n < range.min || n > range.max)) {
+          throw new ScopeCompileError(
+            `parameter '${def.name}'=${n} out of range ${def.validation}`,
+            { scopeId, parameter: def.name }
+          );
+        }
+      }
+      return n;
+    }
+    case "Enum": {
+      if (Array.isArray(def.validation) && !def.validation.includes(String(value))) {
+        throw new ScopeCompileError(
+          `parameter '${def.name}'='${String(value)}' is not one of [${def.validation.join(", ")}]`,
+          { scopeId, parameter: def.name }
+        );
+      }
+      return value;
+    }
+    case "AgentDID": {
+      if (typeof value !== "string" || !arpSpec.DID_URI_REGEX.test(value)) {
+        throw new ScopeCompileError(
+          `parameter '${def.name}' must be a valid DID URI`,
+          { scopeId, parameter: def.name }
+        );
+      }
+      return value;
+    }
+    case "AgentDIDList": {
+      if (!Array.isArray(value) || value.length === 0) {
+        throw new ScopeCompileError(
+          `parameter '${def.name}' must be a non-empty array of DID URIs`,
+          { scopeId, parameter: def.name }
+        );
+      }
+      for (const entry of value) {
+        if (typeof entry !== "string" || !arpSpec.DID_URI_REGEX.test(entry)) {
+          throw new ScopeCompileError(
+            `parameter '${def.name}' contains an invalid DID URI: ${String(entry)}`,
+            { scopeId, parameter: def.name }
+          );
+        }
+      }
+      return value;
+    }
+    case "ToolIDList":
+    case "AttributeList":
+    case "EmailList": {
+      if (!Array.isArray(value)) {
+        throw new ScopeCompileError(
+          `parameter '${def.name}' must be an array`,
+          { scopeId, parameter: def.name }
+        );
+      }
+      return value;
+    }
+    case "ProjectID": {
+      if (typeof value !== "string" || value.trim() === "") {
+        throw new ScopeCompileError(
+          `parameter '${def.name}' must be a non-empty string`,
+          { scopeId, parameter: def.name }
+        );
+      }
+      return value;
+    }
+    case "Duration":
+    case "Timezone":
+    case "IANATimezone": {
+      if (typeof value !== "string" || value.trim() === "") {
+        throw new ScopeCompileError(
+          `parameter '${def.name}' must be a non-empty string`,
+          { scopeId, parameter: def.name }
+        );
+      }
+      return value;
+    }
+  }
+}
+function buildHandlebarsContext(audienceDid, scope, validated) {
+  const ctx = {
+    audience_did: audienceDid,
+    ...validated
+  };
+  for (const [key, value] of Object.entries(validated)) {
+    if (Array.isArray(value)) {
+      ctx[`${key}_json`] = JSON.stringify(value);
+      ctx[`${key}_display`] = value.map((v) => String(v)).join(", ");
+    }
+  }
+  if (scope.id === "calendar.events.read") {
+    ctx.include_private_flag = (validated.include_private ?? scope.parameters.find((p) => p.name === "include_private")?.default) === "yes";
+  }
+  return ctx;
+}
+function compileScope({
+  scope,
+  params = {},
+  audienceDid
+}) {
+  if (!arpSpec.DID_URI_REGEX.test(audienceDid)) {
+    throw new ScopeCompileError(`audienceDid '${audienceDid}' is not a valid DID URI`, {
+      scopeId: scope.id
+    });
+  }
+  const validated = {};
+  for (const def of scope.parameters) {
+    validated[def.name] = validateParameter(scope.id, def, params[def.name]);
+  }
+  const ctx = buildHandlebarsContext(audienceDid, scope, validated);
+  const template = Handlebars__default.default.compile(scope.cedar_template, { noEscape: true });
+  const rendered = template(ctx);
+  return normalizeBareEntityTypes(rendered.trim());
+}
+function normalizeBareEntityTypes(cedar) {
+  return cedar.replace(
+    /(principal|resource)\s*==\s*([A-Z][A-Za-z0-9_]*)(?=\s*[,)\n])/g,
+    "$1 is $2"
+  );
+}
+
+// src/bundle-compiler.ts
+var BundleCompileError = class extends Error {
+  scopeId;
+  conflict;
+  constructor(message, opts) {
+    super(message);
+    this.name = "BundleCompileError";
+    if (opts?.scopeId !== void 0) this.scopeId = opts.scopeId;
+    if (opts?.conflict !== void 0) this.conflict = opts.conflict;
+  }
+};
+function indexCatalog(catalog) {
+  const map = /* @__PURE__ */ new Map();
+  for (const scope of catalog) {
+    map.set(scope.id, scope);
+  }
+  return map;
+}
+function expandImplications(seed, catalog) {
+  const order = [];
+  const visited = /* @__PURE__ */ new Set();
+  const impliedBy = /* @__PURE__ */ new Map();
+  const queue = seed.map((id) => ({
+    id,
+    parent: null
+  }));
+  while (queue.length > 0) {
+    const { id, parent } = queue.shift();
+    if (visited.has(id)) continue;
+    visited.add(id);
+    const scope = catalog.get(id);
+    if (!scope) {
+      throw new BundleCompileError(`unknown scope id '${id}'`, { scopeId: id });
+    }
+    order.push(id);
+    if (parent !== null && !impliedBy.has(id)) impliedBy.set(id, parent);
+    for (const implied of scope.implies) {
+      if (!visited.has(implied)) {
+        queue.push({ id: implied, parent: id });
+      }
+    }
+  }
+  return { order, impliedBy };
+}
+function detectConflicts(expanded, catalog) {
+  const set = new Set(expanded);
+  for (const id of expanded) {
+    const scope = catalog.get(id);
+    if (!scope) continue;
+    for (const conflict of scope.conflicts_with) {
+      if (set.has(conflict)) {
+        throw new BundleCompileError(
+          `scope '${id}' conflicts with '${conflict}' \u2014 cannot coexist in the same bundle`,
+          { conflict: [id, conflict] }
+        );
+      }
+    }
+  }
+}
+function resolveParamsForScope(scope, paramsMap, impliedBy, idx) {
+  const own = { ...paramsMap[scope.id] ?? {} };
+  let parentId = impliedBy.get(scope.id);
+  while (parentId) {
+    const parentParams = paramsMap[parentId];
+    if (parentParams) {
+      for (const [k, v] of Object.entries(parentParams)) {
+        if (own[k] === void 0) own[k] = v;
+      }
+    }
+    const grandparentId = impliedBy.get(parentId);
+    parentId = grandparentId && grandparentId !== parentId ? grandparentId : void 0;
+  }
+  return own;
+}
+function compileBundle({
+  scopeIds,
+  paramsMap = {},
+  audienceDid,
+  catalog
+}) {
+  const idx = indexCatalog(catalog);
+  const { order, impliedBy } = expandImplications(scopeIds, idx);
+  detectConflicts(order, idx);
+  const policies = [];
+  const obligations = [];
+  for (const id of order) {
+    const scope = idx.get(id);
+    if (!scope) continue;
+    const params = resolveParamsForScope(scope, paramsMap, impliedBy);
+    try {
+      policies.push(
+        compileScope({
+          scope,
+          audienceDid,
+          params
+        })
+      );
+    } catch (e) {
+      if (e instanceof ScopeCompileError) throw e;
+      throw new BundleCompileError(
+        `failed to compile scope '${id}': ${e.message}`,
+        { scopeId: id }
+      );
+    }
+    for (const ob of scope.obligations_forced) {
+      obligations.push({ type: ob.type, params: ob.params });
+    }
+  }
+  return { policies, obligations, expandedScopeIds: order };
+}
+
+// src/bundles.ts
+var BUNDLES = [
+  {
+    id: "bundle.project_collaboration.v1",
+    version: "1.0.0",
+    label: "Project collaboration",
+    description: "Collaborate on a project \u2014 read files, task status, and notes; no writes or external sharing.",
+    scopes: [
+      { id: "files.projects.list" },
+      { id: "files.project.metadata.read", params: { project_id: "<user-picks>" } },
+      { id: "files.project.files.read", params: { project_id: "<user-picks>", max_size_mb: 25 } },
+      { id: "files.project.files.summarize", params: { project_id: "<user-picks>", max_output_words: 2e3 } },
+      { id: "tasks.list", params: { project_id: "<user-picks>" } },
+      { id: "tasks.read", params: { project_id: "<user-picks>" } },
+      { id: "tasks.status.update", params: { project_id: "<user-picks>" } },
+      { id: "notes.search", params: { collection_id: "<user-picks>" } },
+      { id: "notes.read", params: { collection_id: "<user-picks>" } }
+    ]
+  },
+  {
+    id: "bundle.scheduling_assistant.v1",
+    version: "1.0.0",
+    label: "Scheduling assistant",
+    description: "Coordinate meetings on your calendar.",
+    scopes: [
+      { id: "calendar.availability.read", params: { days_ahead: 14 } },
+      {
+        id: "calendar.events.propose",
+        params: { max_attendees: 10, max_duration_min: 60 }
+      },
+      { id: "contacts.search", params: { attribute_allowlist: ["name", "email"] } },
+      { id: "messaging.relay.to_principal" }
+    ]
+  },
+  {
+    id: "bundle.research_agent.v1",
+    version: "1.0.0",
+    label: "Research agent",
+    description: "Pull research without writing.",
+    scopes: [
+      { id: "files.projects.list" },
+      { id: "files.project.files.read", params: { project_id: "<user-picks>", max_size_mb: 25 } },
+      { id: "files.project.files.summarize", params: { project_id: "<user-picks>", max_output_words: 2e3 } },
+      { id: "notes.search", params: { collection_id: "<user-picks>" } },
+      { id: "notes.read", params: { collection_id: "<user-picks>" } },
+      { id: "knowledge.query", params: { kb_id: "<user-picks>", max_tokens: 8e3 } },
+      { id: "credentials.proof.zk.request", params: { attribute: "verified_human" } }
+    ]
+  },
+  {
+    id: "bundle.procurement_agent.v1",
+    version: "1.0.0",
+    label: "Procurement agent",
+    description: "Buy things under tight caps.",
+    scopes: [
+      { id: "payments.quote.request" },
+      {
+        id: "payments.authorize.capped",
+        params: { max_per_txn_usd: 25, max_per_30d_usd: 200 }
+      },
+      { id: "payments.history.read", params: { days_back: 90 } },
+      { id: "messaging.relay.to_principal" }
+    ]
+  },
+  {
+    id: "bundle.executive_assistant.v1",
+    version: "1.0.0",
+    label: "Executive assistant",
+    description: "Broad assistant; step-up on anything external-facing.",
+    scopes: [
+      { id: "calendar.availability.read", params: { days_ahead: 14 } },
+      {
+        id: "calendar.events.propose",
+        params: { max_attendees: 10, max_duration_min: 60 }
+      },
+      { id: "calendar.events.modify" },
+      { id: "messaging.email.summary" },
+      { id: "messaging.email.draft.compose" },
+      { id: "messaging.email.send.reviewed", params: { recipient_allowlist: [] } },
+      { id: "contacts.search", params: { attribute_allowlist: ["name", "email"] } },
+      { id: "tasks.list", params: { project_id: "<user-picks>" } },
+      { id: "tasks.read", params: { project_id: "<user-picks>" } },
+      { id: "tasks.create", params: { project_id: "<user-picks>", max_per_day: 50 } },
+      { id: "tasks.status.update", params: { project_id: "<user-picks>" } },
+      { id: "notes.search", params: { collection_id: "<user-picks>" } },
+      { id: "notes.read", params: { collection_id: "<user-picks>" } },
+      { id: "notes.write", params: { collection_id: "<user-picks>", max_per_day: 100 } },
+      { id: "work.status.read" },
+      { id: "work.reports.summary", params: { period: "week" } }
+    ]
+  }
+];
+function findBundle(id) {
+  return BUNDLES.find((b) => b.id === id);
+}
+
+exports.BUNDLES = BUNDLES;
+exports.BundleCompileError = BundleCompileError;
+exports.ScopeCompileError = ScopeCompileError;
+exports.ScopeLoadError = ScopeLoadError;
+exports.buildCatalogManifest = buildCatalogManifest;
+exports.canonicalize = canonicalize;
+exports.compileBundle = compileBundle;
+exports.compileScope = compileScope;
+exports.findBundle = findBundle;
+exports.loadScopeFile = loadScopeFile;
+exports.loadScopesFromDirectory = loadScopesFromDirectory;
+exports.sha256Hex = sha256Hex;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map