canopycms 0.0.67-int.90 → 0.0.67

package/dist/authorization/helpers.d.ts

@@ -1,14 +1,7 @@
 /**
- * Authorization helper functions
- *
- * Simple utilities for checking user roles and permissions.
- */
-/**
- * Reserved groups for CanopyCMS permission system.
- *
- * These groups have special meaning and cannot be deleted or renamed.
- * - Admins: Full access to all CMS operations
- * - Reviewers: Can review branches, request changes, approve PRs
+ * Reserved groups for the CanopyCMS permission system; they cannot be deleted
+ * or renamed. Admins have full access to every CMS operation; Reviewers can
+ * review branches, request changes and approve PRs.
  *
  * SECURITY: membership in a reserved group grants privilege, so these IDs must
  * only ever come from Canopy-managed sources (internal groups in
@@ -21,30 +14,18 @@ export declare const RESERVED_GROUPS: {
     readonly REVIEWERS: "Reviewers";
 };
 export type ReservedGroupId = (typeof RESERVED_GROUPS)[keyof typeof RESERVED_GROUPS];
-/**
- * Check if a group ID is a reserved group
- */
 export declare function isReservedGroup(groupId: string): groupId is ReservedGroupId;
 /**
  * Remove reserved privileged group IDs (Admins, Reviewers) from a group list.
  *
- * SECURITY (SEC-H1): apply this to externally-supplied group lists (identity
- * provider groups) before merging them into a user's effective groups, so a
- * provider-controlled group name can never grant CanopyCMS privilege.
- * Non-reserved groups pass through unchanged and remain usable for ordinary
- * path/branch ACL membership.
+ * SECURITY: apply this to identity-provider group lists before merging them
+ * into a user's effective groups, so a provider-controlled group name can never
+ * grant CanopyCMS privilege. Non-reserved groups pass through unchanged and
+ * remain usable for ordinary path/branch ACL membership.
  */
 export declare function stripReservedGroups<T extends string>(groups: readonly T[]): T[];
-/**
- * Check if user is in the Admins group
- */
 export declare function isAdmin(groups: readonly string[] | undefined): boolean;
-/**
- * Check if user is in the Reviewers group (or is an Admin, since Admins can do everything)
- */
+/** True for the Reviewers group and for Admins, who can do everything. */
 export declare function isReviewer(groups: readonly string[] | undefined): boolean;
-/**
- * Check if user has privileged access (Admin or Reviewer)
- * Used for operations that require elevated permissions but not full admin
- */
+/** For operations that need elevated rights but not full admin. */
 export declare function isPrivileged(groups: readonly string[] | undefined): boolean;

package/dist/authorization/helpers.js

@@ -1,14 +1,7 @@
 /**
- * Authorization helper functions
- *
- * Simple utilities for checking user roles and permissions.
- */
-/**
- * Reserved groups for CanopyCMS permission system.
- *
- * These groups have special meaning and cannot be deleted or renamed.
- * - Admins: Full access to all CMS operations
- * - Reviewers: Can review branches, request changes, approve PRs
+ * Reserved groups for the CanopyCMS permission system; they cannot be deleted
+ * or renamed. Admins have full access to every CMS operation; Reviewers can
+ * review branches, request changes and approve PRs.
  *
  * SECURITY: membership in a reserved group grants privilege, so these IDs must
  * only ever come from Canopy-managed sources (internal groups in
@@ -20,40 +13,28 @@ export const RESERVED_GROUPS = {
     ADMINS: 'Admins',
     REVIEWERS: 'Reviewers',
 };
-/**
- * Check if a group ID is a reserved group
- */
 export function isReservedGroup(groupId) {
     return Object.values(RESERVED_GROUPS).includes(groupId);
 }
 /**
  * Remove reserved privileged group IDs (Admins, Reviewers) from a group list.
  *
- * SECURITY (SEC-H1): apply this to externally-supplied group lists (identity
- * provider groups) before merging them into a user's effective groups, so a
- * provider-controlled group name can never grant CanopyCMS privilege.
- * Non-reserved groups pass through unchanged and remain usable for ordinary
- * path/branch ACL membership.
+ * SECURITY: apply this to identity-provider group lists before merging them
+ * into a user's effective groups, so a provider-controlled group name can never
+ * grant CanopyCMS privilege. Non-reserved groups pass through unchanged and
+ * remain usable for ordinary path/branch ACL membership.
  */
 export function stripReservedGroups(groups) {
     return groups.filter((group) => !isReservedGroup(group));
 }
-/**
- * Check if user is in the Admins group
- */
 export function isAdmin(groups) {
     return groups?.includes(RESERVED_GROUPS.ADMINS) ?? false;
 }
-/**
- * Check if user is in the Reviewers group (or is an Admin, since Admins can do everything)
- */
+/** True for the Reviewers group and for Admins, who can do everything. */
 export function isReviewer(groups) {
     return isAdmin(groups) || (groups?.includes(RESERVED_GROUPS.REVIEWERS) ?? false);
 }
-/**
- * Check if user has privileged access (Admin or Reviewer)
- * Used for operations that require elevated permissions but not full admin
- */
+/** For operations that need elevated rights but not full admin. */
 export function isPrivileged(groups) {
     return isReviewer(groups);
 }

package/dist/authorization/index.d.ts

@@ -1,29 +1,7 @@
 /**
- * Authorization module for CanopyCMS
- *
- * This module provides a unified API for checking user access to branches and content.
- *
- * ## Quick Start
- *
- * For most use cases, use `checkContentAccess` which handles both branch and path permissions:
- *
- * ```ts
- * import { checkContentAccess } from './authorization.js'
- *
- * const result = await checkContentAccess(deps, context, branchRoot, 'content/posts/post.mdx', user, 'edit')
- * if (result.allowed) {
- *   // User can edit the file
- * }
- * ```
- *
- * ## Module Structure
- *
- * - `content.ts` - Combined branch + path access (main entry point)
- * - `branch.ts` - Branch-level access control
- * - `path.ts` - Path-level permissions
- * - `helpers.ts` - Utility functions (isAdmin, isReviewer, etc.)
- * - `permissions/` - Permissions file schema and loader
- * - `groups/` - Groups file schema and loader
+ * Authorization for CanopyCMS: checking user access to branches and content.
+ * Most callers want `checkContentAccess(deps, context, branchRoot, path, user,
+ * level)`, which covers both the branch and the path layer.
  */
 export type { BranchAccessResult, PathPermissionResult, ContentAccessResult, ContentAccessDeps, PermissionPath, } from './types.js';
 export { parsePermissionPath } from './validation.js';

package/dist/authorization/index.js

@@ -1,46 +1,14 @@
 /**
- * Authorization module for CanopyCMS
- *
- * This module provides a unified API for checking user access to branches and content.
- *
- * ## Quick Start
- *
- * For most use cases, use `checkContentAccess` which handles both branch and path permissions:
- *
- * ```ts
- * import { checkContentAccess } from './authorization.js'
- *
- * const result = await checkContentAccess(deps, context, branchRoot, 'content/posts/post.mdx', user, 'edit')
- * if (result.allowed) {
- *   // User can edit the file
- * }
- * ```
- *
- * ## Module Structure
- *
- * - `content.ts` - Combined branch + path access (main entry point)
- * - `branch.ts` - Branch-level access control
- * - `path.ts` - Path-level permissions
- * - `helpers.ts` - Utility functions (isAdmin, isReviewer, etc.)
- * - `permissions/` - Permissions file schema and loader
- * - `groups/` - Groups file schema and loader
+ * Authorization for CanopyCMS: checking user access to branches and content.
+ * Most callers want `checkContentAccess(deps, context, branchRoot, path, user,
+ * level)`, which covers both the branch and the path layer.
  */
-// Validation
 export { parsePermissionPath } from './validation.js';
-// Main content access (recommended for most cases)
 export { checkContentAccess, createCheckContentAccess, createContentAccessChecker, } from './content.js';
-// Branch-level access
 export { checkBranchAccessWithDefault, createCheckBranchAccess, canPerformWorkflowAction, } from './branch.js';
-// Protected base branch (submit-block + read-only predicate)
 export { getBranchProtection, getBranchWriteProtection, } from './protected-branch.js';
-// Path-level access
 export { checkPathAccess, createCheckPathAccess, resolveDefaultPathAccess } from './path.js';
-// Helper functions
 export { RESERVED_GROUPS, isReservedGroup, stripReservedGroups, isAdmin, isReviewer, isPrivileged, } from './helpers.js';
-// Permissions file handling
 export { PermissionsFileSchema, createDefaultPermissionsFile, loadPermissionsFile, loadPathPermissions, mutatePermissionsFile, ensurePermissionsFile, } from './permissions/index.js';
-// Groups file handling
 export { GroupsFileSchema, createDefaultGroupsFile, loadGroupsFile, loadInternalGroups, deriveInternalGroups, mutateGroupsFile, } from './groups/index.js';
-// Settings file store — cross-host layered locking shared by
-// permissions.json and groups.json (see authorization/settings-file-store.ts)
 export { mutateSettingsJsonFile, SettingsFileConflictError, SettingsVersionConflictError, } from './settings-file-store.js';

package/dist/authorization/path.d.ts

@@ -1,23 +1,19 @@
-/**
- * Path-level authorization
- *
- * Handles checking if a user can access a specific path based on permission rules.
- */
 import type { PathPermission, DefaultPathAccess, PermissionLevel } from '../config/index.js';
 import type { CanopyUser } from '../user.js';
 import type { PathPermissionResult } from './types.js';
 import type { PhysicalPath } from '../paths/types.js';
 /**
- * Resolve a `defaultPathAccess` config value to an 'allow'/'deny' verdict for one
- * permission level. String form applies the same value to every level (unchanged
- * behavior). Object form looks up the level; an absent level resolves to 'deny'
- * (fail-closed), so scoping e.g. `{ read: 'allow' }` doesn't accidentally open
- * edit/review.
+ * Resolve `defaultPathAccess` to an 'allow'/'deny' verdict for one permission
+ * level. String form applies to every level; object form looks up the level,
+ * and an absent level resolves to 'deny' (fail-closed) so `{ read: 'allow' }`
+ * cannot accidentally open edit/review.
+ * @internal Exported for tests.
  */
 export declare function resolveDefaultPathAccess(defaultAccess: DefaultPathAccess, level: PermissionLevel): 'allow' | 'deny';
 /**
  * Evaluate access for a relative path against config-defined rules.
  * Uses defaultAccess when no rule matches. First matching rule wins.
+ * @internal Exported for tests.
  */
 export declare function checkPathAccess({ rules, relativePath, user, defaultAccess, level, }: {
     rules: PathPermission[];
@@ -26,9 +22,6 @@ export declare function checkPathAccess({ rules, relativePath, user, defaultAcce
     defaultAccess: DefaultPathAccess;
     level: PermissionLevel;
 }): PathPermissionResult;
-/**
- * Factory to bind rules and defaultAccess once.
- */
 export declare function createCheckPathAccess(rules: PathPermission[], defaultAccess: DefaultPathAccess): (input: {
     relativePath: PhysicalPath;
     user: CanopyUser;

package/dist/authorization/path.js

@@ -1,31 +1,17 @@
-/**
- * Path-level authorization
- *
- * Handles checking if a user can access a specific path based on permission rules.
- */
 import path from 'node:path';
 import { minimatch } from 'minimatch';
 import { isAdmin } from './helpers.js';
-/**
- * Normalize a path for consistent matching
- */
 function normalize(p) {
     const normalized = p.split(path.sep).join('/');
     return normalized.replace(/^\.?\/*/, '');
 }
-/**
- * Check if a path matches a permission rule
- */
 function matchesRule(rule, relativePath) {
     return minimatch(relativePath, rule.path, { dot: true });
 }
-/**
- * Check if user matches a permission target
- */
 function isAllowedByTarget(target, user) {
     const hasUserConstraint = !!target.allowedUsers?.length;
     const hasGroupConstraint = !!target.allowedGroups?.length;
-    // No constraints means allowed (rule applies to everyone)
+    // A target with no constraints applies to everyone.
     if (!hasUserConstraint && !hasGroupConstraint) {
         return true;
     }
@@ -34,11 +20,11 @@ function isAllowedByTarget(target, user) {
     return Boolean(matchesUser || matchesGroup);
 }
 /**
- * Resolve a `defaultPathAccess` config value to an 'allow'/'deny' verdict for one
- * permission level. String form applies the same value to every level (unchanged
- * behavior). Object form looks up the level; an absent level resolves to 'deny'
- * (fail-closed), so scoping e.g. `{ read: 'allow' }` doesn't accidentally open
- * edit/review.
+ * Resolve `defaultPathAccess` to an 'allow'/'deny' verdict for one permission
+ * level. String form applies to every level; object form looks up the level,
+ * and an absent level resolves to 'deny' (fail-closed) so `{ read: 'allow' }`
+ * cannot accidentally open edit/review.
+ * @internal Exported for tests.
  */
 export function resolveDefaultPathAccess(defaultAccess, level) {
     if (typeof defaultAccess === 'string')
@@ -48,6 +34,7 @@ export function resolveDefaultPathAccess(defaultAccess, level) {
 /**
  * Evaluate access for a relative path against config-defined rules.
  * Uses defaultAccess when no rule matches. First matching rule wins.
+ * @internal Exported for tests.
  */
 export function checkPathAccess({ rules, relativePath, user, defaultAccess, level, }) {
     const normalizedPath = normalize(relativePath);
@@ -59,10 +46,9 @@ export function checkPathAccess({ rules, relativePath, user, defaultAccess, leve
         if (!matchesRule(rule, normalizedPath)) {
             continue;
         }
-        // Get the permission target for this level
         const target = rule[level];
         if (!target) {
-            // No permissions defined for this level on this rule, continue to next rule
+            // A rule that defines nothing for this level does not decide it.
             continue;
         }
         const allowed = isAllowedByTarget(target, user);
@@ -77,9 +63,6 @@ export function checkPathAccess({ rules, relativePath, user, defaultAccess, leve
         reason: 'no_rule_match',
     };
 }
-/**
- * Factory to bind rules and defaultAccess once.
- */
 export function createCheckPathAccess(rules, defaultAccess) {
     return (input) => checkPathAccess({ ...input, rules, defaultAccess });
 }

package/dist/authorization/permissions/index.d.ts

@@ -1,5 +1,2 @@
-/**
- * Permissions module exports
- */
 export { PermissionsFileSchema, createDefaultPermissionsFile, type PermissionsFile } from './schema.js';
 export { loadPermissionsFile, loadPathPermissions, mutatePermissionsFile, ensurePermissionsFile, } from './loader.js';

package/dist/authorization/permissions/index.js

@@ -1,5 +1,2 @@
-/**
- * Permissions module exports
- */
 export { PermissionsFileSchema, createDefaultPermissionsFile } from './schema.js';
 export { loadPermissionsFile, loadPathPermissions, mutatePermissionsFile, ensurePermissionsFile, } from './loader.js';

package/dist/authorization/permissions/loader.d.ts

@@ -1,46 +1,33 @@
 /**
- * Permissions file loader
- *
- * Handles loading path permissions from the filesystem and mutating
- * permissions.json under the cross-host layered lock in
- * authorization/settings-file-store.ts.
+ * Loads path permissions, and mutates permissions.json under the cross-host
+ * layered lock in authorization/settings-file-store.ts.
  */
 import type { PathPermission } from '../../config/index.js';
 import type { PermissionsFile } from './schema.js';
 import type { OperatingMode } from '../../operating-mode/index.js';
 import type { OccWriteResult } from '../../utils/occ-json-write.js';
-/**
- * Load full permissions file (for version checking)
- * Returns null if file doesn't exist.
- *
- * @param repoRoot - Repository root directory
- * @param mode - Operating mode (determines file path)
- */
+/** Returns null when the file doesn't exist. */
 export declare function loadPermissionsFile(repoRoot: string, mode: OperatingMode): Promise<PermissionsFile | null>;
 /**
- * Load path permissions from .canopycms/permissions.json (or .local.json in dev mode)
- * Returns empty array if file doesn't exist (no restrictions).
- *
- * @param repoRoot - Repository root directory
- * @param mode - Operating mode (determines file path)
+ * Loads .canopycms/permissions.json (permissions.local.json in dev mode).
+ * Returns an empty array when the file doesn't exist: no restrictions.
  */
 export declare function loadPathPermissions(repoRoot: string, mode: OperatingMode): Promise<PathPermission[]>;
 /**
- * Mutate permissions.json (or .local.json in dev mode) under the full
- * cross-host lock + OCC-retry stack (see
- * authorization/settings-file-store.ts). `mutate` is called with the
- * current parsed file (`null` if it doesn't exist yet) and the version to
- * write under; it returns the next raw payload, or `null` for a deliberate
- * no-op. The returned payload is validated against
- * {@link PermissionsFileSchema} before being written, preserving the
- * previous validate-before-write behavior of the old `savePathPermissions`.
+ * Mutate permissions.json (permissions.local.json in dev mode) under the full
+ * cross-host lock + OCC-retry stack (see authorization/settings-file-store.ts).
+ * `mutate` receives the current parsed file (`null` if absent) and the version
+ * to write under, and returns the next raw payload or `null` for a deliberate
+ * no-op. The payload is validated against {@link PermissionsFileSchema} before
+ * writing.
  */
 export declare function mutatePermissionsFile(repoRoot: string, mode: OperatingMode, mutate: (current: PermissionsFile | null, version: number) => Record<string, unknown> | null, options?: {
     settleMs?: number;
     maxAttempts?: number;
 }): Promise<OccWriteResult | null>;
 /**
- * Initialize permissions file if it doesn't exist. A no-op when the file is
- * already present (the mutator returns `null`, so no write happens).
+ * Create the permissions file if it doesn't exist; a no-op when it is already
+ * present (the mutator returns `null`, so no write happens).
+ * @internal Exported for tests.
  */
 export declare function ensurePermissionsFile(repoRoot: string, userId: string, mode: OperatingMode): Promise<void>;

package/dist/authorization/permissions/loader.js

@@ -1,27 +1,15 @@
 /**
- * Permissions file loader
- *
- * Handles loading path permissions from the filesystem and mutating
- * permissions.json under the cross-host layered lock in
- * authorization/settings-file-store.ts.
+ * Loads path permissions, and mutates permissions.json under the cross-host
+ * layered lock in authorization/settings-file-store.ts.
  */
 import fs from 'node:fs/promises';
 import { PermissionsFileSchema } from './schema.js';
 import { operatingStrategy } from '../../operating-mode/index.js';
 import { mutateSettingsJsonFile } from '../settings-file-store.js';
-/**
- * Get the appropriate permissions file path based on mode
- */
 function getPermissionsFilePath(repoRoot, mode) {
     return operatingStrategy(mode).getPermissionsFilePath(repoRoot);
 }
-/**
- * Load full permissions file (for version checking)
- * Returns null if file doesn't exist.
- *
- * @param repoRoot - Repository root directory
- * @param mode - Operating mode (determines file path)
- */
+/** Returns null when the file doesn't exist. */
 export async function loadPermissionsFile(repoRoot, mode) {
     const permissionsPath = getPermissionsFilePath(repoRoot, mode);
     try {
@@ -31,35 +19,28 @@ export async function loadPermissionsFile(repoRoot, mode) {
         return validated;
     }
     catch (error) {
-        // File doesn't exist
         if (error.code === 'ENOENT') {
             return null;
         }
-        // Parse/validation error - this is more serious
         console.error('CanopyCMS: Failed to parse permissions file', error);
         throw new Error(`Invalid permissions file: ${error instanceof Error ? error.message : 'unknown error'}`);
     }
 }
 /**
- * Load path permissions from .canopycms/permissions.json (or .local.json in dev mode)
- * Returns empty array if file doesn't exist (no restrictions).
- *
- * @param repoRoot - Repository root directory
- * @param mode - Operating mode (determines file path)
+ * Loads .canopycms/permissions.json (permissions.local.json in dev mode).
+ * Returns an empty array when the file doesn't exist: no restrictions.
  */
 export async function loadPathPermissions(repoRoot, mode) {
     const file = await loadPermissionsFile(repoRoot, mode);
     return file?.pathPermissions ?? [];
 }
 /**
- * Mutate permissions.json (or .local.json in dev mode) under the full
- * cross-host lock + OCC-retry stack (see
- * authorization/settings-file-store.ts). `mutate` is called with the
- * current parsed file (`null` if it doesn't exist yet) and the version to
- * write under; it returns the next raw payload, or `null` for a deliberate
- * no-op. The returned payload is validated against
- * {@link PermissionsFileSchema} before being written, preserving the
- * previous validate-before-write behavior of the old `savePathPermissions`.
+ * Mutate permissions.json (permissions.local.json in dev mode) under the full
+ * cross-host lock + OCC-retry stack (see authorization/settings-file-store.ts).
+ * `mutate` receives the current parsed file (`null` if absent) and the version
+ * to write under, and returns the next raw payload or `null` for a deliberate
+ * no-op. The payload is validated against {@link PermissionsFileSchema} before
+ * writing.
  */
 export async function mutatePermissionsFile(repoRoot, mode, mutate, options) {
     const permissionsPath = getPermissionsFilePath(repoRoot, mode);
@@ -75,8 +56,9 @@ export async function mutatePermissionsFile(repoRoot, mode, mutate, options) {
     });
 }
 /**
- * Initialize permissions file if it doesn't exist. A no-op when the file is
- * already present (the mutator returns `null`, so no write happens).
+ * Create the permissions file if it doesn't exist; a no-op when it is already
+ * present (the mutator returns `null`, so no write happens).
+ * @internal Exported for tests.
  */
 export async function ensurePermissionsFile(repoRoot, userId, mode) {
     await mutatePermissionsFile(repoRoot, mode, (current) => {

package/dist/authorization/permissions/schema.d.ts

@@ -1,14 +1,8 @@
-/**
- * Schema for permissions.json file
- */
 import { z } from 'zod';
 import type { CanopyUserId } from '../../types.js';
 import type { PermissionPath } from '../types.js';
 /**
  * Schema for .canopycms/permissions.json
- *
- * SECURITY: Permission paths are validated to prevent path traversal attacks.
- * Any path containing '..' or other traversal sequences will be rejected.
  */
 export declare const PermissionsFileSchema: z.ZodObject<{
     version: z.ZodOptional<z.ZodNumber>;
@@ -129,5 +123,6 @@ export type PermissionsFile = z.infer<typeof PermissionsFileSchema>;
 /**
  * Default permissions file. Omits `version`/`writeId` — the writer
  * (mutateSettingsJsonFile via writeOccJsonFile) manages those.
+ * @internal Exported for tests.
  */
 export declare function createDefaultPermissionsFile(userId: CanopyUserId): PermissionsFile;

package/dist/authorization/permissions/schema.js

@@ -1,15 +1,10 @@
-/**
- * Schema for permissions.json file
- */
 import { z } from 'zod';
 import { parsePermissionPath } from '../validation.js';
 const permissionTargetSchema = z.object({
     allowedUsers: z.array(z.string()).optional(),
     allowedGroups: z.array(z.string()).optional(),
 });
-/**
- * Zod schema for PermissionPath - validates and prevents path traversal attacks.
- */
+/** PermissionPath field: rejects path traversal via parsePermissionPath. */
 const permissionPathSchema = z
     .string()
     .min(1)
@@ -26,15 +21,12 @@ const permissionPathSchema = z
 });
 /**
  * Schema for .canopycms/permissions.json
- *
- * SECURITY: Permission paths are validated to prevent path traversal attacks.
- * Any path containing '..' or other traversal sequences will be rejected.
  */
 export const PermissionsFileSchema = z.object({
-    // Managed by writeOccJsonFile (see authorization/settings-file-store.ts) —
-    // the single OCC counter for this file. Optional so a hand-written file
-    // with no version field parses as version 0. A legacy `contentVersion`
-    // field (if present) is silently stripped by this non-strict zod parse.
+    // Managed by writeOccJsonFile (see authorization/settings-file-store.ts):
+    // the single OCC counter for this file. Optional so a hand-written file with
+    // no version field parses as version 0; a stray `contentVersion` key is
+    // silently stripped by this non-strict zod parse.
     version: z.number().int().nonnegative().optional(),
     writeId: z.string().optional(),
     updatedAt: z.string().datetime(),
@@ -49,6 +41,7 @@ export const PermissionsFileSchema = z.object({
 /**
  * Default permissions file. Omits `version`/`writeId` — the writer
  * (mutateSettingsJsonFile via writeOccJsonFile) manages those.
+ * @internal Exported for tests.
  */
 export function createDefaultPermissionsFile(userId) {
     return {