canopycms 0.0.68-int.98 → 0.1.0

package/dist/assets/types.d.ts

@@ -41,6 +41,12 @@ export interface PublicObject {
     contentDisposition?: string;
     cacheControl?: string;
 }
+/**
+ * What a create-only write did. Every key the store writes this way is content-addressed, so no
+ * correct writer ever replaces an object: `already-exists` means an object was already at the key
+ * and was left alone.
+ */
+export type CreateOnlyResult = 'created' | 'already-exists';
 export interface AssetStore {
     readonly capabilities: {
         directUpload: boolean;
@@ -49,26 +55,47 @@ export interface AssetStore {
     writeStaging(stagingKey: string, data: Uint8Array, contentType?: string): Promise<void>;
     readStaging(stagingKey: string): Promise<Uint8Array | null>;
     deleteStaging(stagingKey: string): Promise<void>;
+    /** Create-only; see `CreateOnlyResult`. */
     putOriginal(input: {
         hash32: string;
         ext: string;
         data: Uint8Array;
         contentType: string;
-    }): Promise<void>;
-    readOriginal(hash32: string): Promise<{
+    }): Promise<CreateOnlyResult>;
+    /**
+     * `ext` is where the original is expected (its meta's `ext`): that key is read first, and any
+     * `{hash32}.*` is looked for only on a miss. A hit needs no list permission; on S3 without
+     * `s3:ListBucket` a miss is a 403, which throws.
+     */
+    readOriginal(hash32: string, ext?: string): Promise<{
         data: Uint8Array;
         ext: string;
         contentType?: string;
     } | null>;
+    /** Create-only; see `CreateOnlyResult`. */
     putPublicObject(input: {
         key: string;
         data: Uint8Array;
         contentType: string;
         contentDisposition?: string;
         cacheControl?: string;
-    }): Promise<void>;
+        /** Object tags; bucket lifecycle rules can filter on them. */
+        tags?: Readonly<Record<string, string>>;
+    }): Promise<CreateOnlyResult>;
+    /**
+     * Copy the public object at `sourceKey` to `destKey` inside the store, create-only like
+     * `putPublicObject`. The copy keeps the source's headers and carries no tags. `source-missing`
+     * when nothing is at `sourceKey`.
+     */
+    copyPublicObject(sourceKey: string, destKey: string): Promise<CreateOnlyResult | 'source-missing'>;
     readPublicObject(key: string): Promise<PublicObject | null>;
-    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<'created' | 'already-exists'>;
+    /** Whether a public object exists at `key`, without reading its body. */
+    hasPublicObject(key: string): Promise<boolean>;
+    /** Every public object key under `prefix`, in the store's own pages. S3 only. */
+    listPublicObjectKeys?(prefix: string): AsyncIterable<string>;
+    /** A short-lived URL a browser can GET `key` from directly, or `null` if absent. S3 only. */
+    presignPublicObjectRead?(key: string): Promise<string | null>;
+    putMetaIfAbsent(hash32: string, meta: AssetMeta): Promise<CreateOnlyResult>;
     getMeta(hash32: string): Promise<AssetMeta | null>;
     listMeta(input?: {
         cursor?: string;

package/dist/auth/cache.d.ts

@@ -2,5 +2,5 @@
  * Server-only: these use node:fs/promises and must NOT reach a client bundle.
  * Import them as 'canopycms/auth/cache'.
  */
-export { FileBasedAuthCache, writeAuthCacheSnapshot } from './file-based-auth-cache.js';
+export { FileBasedAuthCache, writeAuthCacheSnapshot, writeAuthSnapshot, type AuthCacheSnapshot, } from './file-based-auth-cache.js';
 export { CachingAuthPlugin } from './caching-auth-plugin.js';

package/dist/auth/cache.js

@@ -2,5 +2,5 @@
  * Server-only: these use node:fs/promises and must NOT reach a client bundle.
  * Import them as 'canopycms/auth/cache'.
  */
-export { FileBasedAuthCache, writeAuthCacheSnapshot } from './file-based-auth-cache.js';
+export { FileBasedAuthCache, writeAuthCacheSnapshot, writeAuthSnapshot, } from './file-based-auth-cache.js';
 export { CachingAuthPlugin } from './caching-auth-plugin.js';

package/dist/auth/caching-auth-plugin.d.ts

@@ -38,6 +38,8 @@ export declare class CachingAuthPlugin implements AuthPlugin {
     authenticate(context: unknown): Promise<AuthenticationResult>;
     searchUsers(query: string, limit?: number): Promise<UserSearchResult[]>;
     getUserMetadata(userId: CanopyUserId): Promise<UserSearchResult | null>;
+    /** One cache read for the whole set, where `getUserMetadata` per id re-stats the files each time. */
+    getUsersMetadata(userIds: CanopyUserId[]): Promise<UserSearchResult[]>;
     getGroupMetadata(groupId: CanopyGroupId): Promise<GroupMetadata | null>;
     listGroups(limit?: number): Promise<GroupMetadata[]>;
 }

package/dist/auth/caching-auth-plugin.js

@@ -1,4 +1,5 @@
 import { createDebugLogger } from '../utils/debug.js';
+import { personName } from './person-name.js';
 const log = createDebugLogger({ prefix: 'CachingAuthPlugin' });
 /**
  * Wraps a token verifier with cached metadata lookups, for environments where
@@ -45,7 +46,7 @@ export class CachingAuthPlugin {
                 success: true,
                 user: {
                     userId: identity.userId,
-                    name: user?.name ?? identity.userId,
+                    name: personName(identity.userId, user?.name),
                     email: user?.email,
                     avatarUrl: user?.avatarUrl,
                     externalGroups,
@@ -62,7 +63,6 @@ export class CachingAuthPlugin {
                 success: true,
                 user: {
                     userId: identity.userId,
-                    name: identity.userId,
                     externalGroups: [],
                 },
             };
@@ -88,6 +88,16 @@ export class CachingAuthPlugin {
             return null;
         }
     }
+    /** One cache read for the whole set, where `getUserMetadata` per id re-stats the files each time. */
+    async getUsersMetadata(userIds) {
+        try {
+            const wanted = new Set(userIds);
+            return (await this.cache.getAllUsers()).filter((u) => wanted.has(u.id));
+        }
+        catch {
+            return [];
+        }
+    }
     async getGroupMetadata(groupId) {
         try {
             return await this.cache.getGroup(groupId);

package/dist/auth/file-based-auth-cache.d.ts

@@ -32,3 +32,11 @@ export declare class FileBasedAuthCache implements AuthCacheProvider {
  * recent snapshot directories are kept.
  */
 export declare function writeAuthCacheSnapshot(cachePath: string, files: Record<string, unknown>): Promise<string>;
+/** One auth provider's users, groups and memberships: what an auth-cache refresh writes. */
+export interface AuthCacheSnapshot {
+    users: UserSearchResult[];
+    groups: GroupMetadata[];
+    memberships: Record<CanopyUserId, CanopyGroupId[]>;
+}
+/** Write `snapshot` as the three files FileBasedAuthCache reads (users.json, orgs.json, memberships.json). */
+export declare function writeAuthSnapshot(cachePath: string, snapshot: AuthCacheSnapshot): Promise<string>;

package/dist/auth/file-based-auth-cache.js

@@ -168,14 +168,13 @@ export async function writeAuthCacheSnapshot(cachePath, files) {
         await fs.rename(tmpPath, finalPath);
     }
     // The symlink target MUST be relative (the bare `snapshot-<ts>` basename),
-    // because writer and reader do not share a mount namespace: in prod the EC2
-    // worker writes through /mnt/efs/workspace/.cache while the CMS Lambda mounts
-    // the /workspace access point and reads the SAME directory as /mnt/efs/.cache.
-    // An absolute target recorded by one is a nonexistent path to the other, and
-    // `resolveActiveCacheDir`'s escape guard then falls back to the flat layout,
-    // where the worker never writes — leaving the Lambda a permanently empty
-    // cache. A relative target resolves against whichever cachePath the reader
-    // was given, so it is correct from both.
+    // because writer and reader are separate hosts (in prod, the EC2 worker and
+    // the CMS Lambda) that each mount EFS themselves, so nothing guarantees they
+    // reach this directory by the same path. An absolute target recorded by one
+    // can be a nonexistent path to the other, and `resolveActiveCacheDir`'s
+    // escape guard then falls back to the flat layout, where the worker never
+    // writes, leaving the reader a permanently empty cache. A relative target
+    // resolves against whichever cachePath the reader was given.
     const currentLink = path.join(cachePath, 'current');
     const tmpLink = path.join(cachePath, `current-${timestamp}`);
     await fs.symlink(path.basename(snapshotDir), tmpLink);
@@ -183,6 +182,17 @@ export async function writeAuthCacheSnapshot(cachePath, files) {
     await cleanupOldSnapshots(cachePath, 2);
     return snapshotDir;
 }
+/** Write `snapshot` as the three files FileBasedAuthCache reads (users.json, orgs.json, memberships.json). */
+export async function writeAuthSnapshot(cachePath, snapshot) {
+    const users = { users: snapshot.users };
+    const groups = { groups: snapshot.groups };
+    const memberships = { memberships: snapshot.memberships };
+    return writeAuthCacheSnapshot(cachePath, {
+        'users.json': users,
+        'orgs.json': groups,
+        'memberships.json': memberships,
+    });
+}
 async function cleanupOldSnapshots(cachePath, keepCount) {
     let entries;
     try {

package/dist/auth/person-name.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The name to show for a person, or undefined when there is none. An id is an internal name
+ * (docs/ux-guidelines.md, "People"), so a name equal to the id is no name.
+ */
+export declare function personName(id: string, name: string | undefined): string | undefined;

package/dist/auth/person-name.js

@@ -0,0 +1,8 @@
+/**
+ * The name to show for a person, or undefined when there is none. An id is an internal name
+ * (docs/ux-guidelines.md, "People"), so a name equal to the id is no name.
+ */
+export function personName(id, name) {
+    const trimmed = name?.trim();
+    return trimmed && trimmed !== id ? trimmed : undefined;
+}

package/dist/auth/plugin.d.ts

@@ -14,7 +14,7 @@ export interface AuthPlugin {
      * groups; core applies bootstrap admins.
      *
      * CREDENTIAL failures (missing, invalid or expired token) RESOLVE to
-     * `{ success: false }` and map to a 401. CONFIGURATION errors (an absent
+     * `{ success: false }` and map to `unauthenticatedStatus` (default 401). CONFIGURATION errors (an absent
      * CLERK_SECRET_KEY, say) may THROW instead: they are operator mistakes, and
      * belong in a loud 500 rather than a quiet auth denial. A custom adapter
      * calling this directly must be ready for that rejection.
@@ -23,6 +23,15 @@ export interface AuthPlugin {
     /** For the permission-management UI. */
     searchUsers(query: string, limit?: number): Promise<UserSearchResult[]>;
     getUserMetadata(userId: CanopyUserId): Promise<UserSearchResult | null>;
+    /**
+     * Looks up many users in as few provider calls as possible, resolving to the users found, in
+     * any order; unknown ids are omitted. Core never passes more than 100 ids at once. Without
+     * it, core falls back to concurrent `getUserMetadata` calls, a few at a time.
+     *
+     * Reject on a provider failure rather than omitting ids: core caches an omitted id as unknown,
+     * as it does a `null` from the `getUserMetadata` fallback.
+     */
+    getUsersMetadata?(userIds: CanopyUserId[]): Promise<UserSearchResult[]>;
     getGroupMetadata(groupId: CanopyGroupId): Promise<GroupMetadata | null>;
     /** For permission UI dropdowns. */
     listGroups(limit?: number): Promise<GroupMetadata[]>;

package/dist/auth/types.d.ts

@@ -6,6 +6,8 @@ export interface UserSearchResult {
     email: string;
     avatarUrl?: string;
 }
+/** What a reader who is not privileged may learn about another user: never the email. */
+export type UserProfile = Pick<UserSearchResult, 'id' | 'name' | 'avatarUrl'>;
 /** Group metadata for the permission UI. */
 export interface GroupMetadata {
     id: CanopyGroupId;

package/dist/auth/user-metadata-lookup.d.ts

@@ -0,0 +1,21 @@
+import type { AuthPlugin } from './plugin.js';
+import type { UserProfile, UserSearchResult } from './types.js';
+import type { CanopyUserId } from '../types.js';
+/**
+ * How long a looked-up user, or the fact that an id is unknown, is served without asking again.
+ * @internal Exported for tests.
+ */
+export declare const USER_METADATA_TTL_MS: number;
+/**
+ * Resolves each id to its user, or `null` when the provider does not know it. Unknown ids are
+ * cached like found ones, so a stale id in permissions.json costs a process one provider call
+ * per TTL. A rejection caches nothing; a `getUserMetadata` that answers `null` on failure is
+ * cached as unknown.
+ */
+export declare function lookupUsersMetadata(plugin: AuthPlugin, userIds: readonly CanopyUserId[]): Promise<Map<CanopyUserId, UserSearchResult | null>>;
+/**
+ * The name and avatar of each id a response may show to any reader, never the email. Callers pass
+ * only ids the requester can already see. Non-string, empty, oversized, bot and anonymous ids are
+ * skipped: the editor labels bots and the anonymous user without a lookup. Unknown ids are absent.
+ */
+export declare function lookupUserProfiles(plugin: AuthPlugin, ids: Iterable<unknown>): Promise<UserProfile[]>;

package/dist/auth/user-metadata-lookup.js

@@ -0,0 +1,116 @@
+import { LRUCache } from 'lru-cache';
+import { CachingAuthPlugin } from './caching-auth-plugin.js';
+import { MAX_USER_METADATA_BATCH } from '../api/users-constants.js';
+import { isSystemUserId } from '../system-users.js';
+import { ANONYMOUS_USER } from '../user.js';
+import { personName } from './person-name.js';
+/**
+ * How long a looked-up user, or the fact that an id is unknown, is served without asking again.
+ * @internal Exported for tests.
+ */
+export const USER_METADATA_TTL_MS = 5 * 60 * 1000;
+const MAX_CACHED_USERS = 5000;
+/** Concurrent `getUserMetadata` calls for a plugin without `getUsersMetadata`. */
+const SINGLE_LOOKUP_CONCURRENCY = 8;
+/**
+ * Per-process, in-memory, never persisted: each process keeps its own copy, so a changed name or
+ * avatar shows everywhere within one TTL. Keyed by plugin so two plugins never share answers.
+ */
+const caches = new WeakMap();
+function cacheFor(plugin) {
+    let cache = caches.get(plugin);
+    if (!cache) {
+        cache = new LRUCache({ max: MAX_CACHED_USERS, ttl: USER_METADATA_TTL_MS });
+        caches.set(plugin, cache);
+    }
+    return cache;
+}
+/**
+ * Resolves each id to its user, or `null` when the provider does not know it. Unknown ids are
+ * cached like found ones, so a stale id in permissions.json costs a process one provider call
+ * per TTL. A rejection caches nothing; a `getUserMetadata` that answers `null` on failure is
+ * cached as unknown.
+ */
+export async function lookupUsersMetadata(plugin, userIds) {
+    const unique = [...new Set(userIds)];
+    // Answered from an in-memory copy of the worker-written file cache; a TTL on top would only
+    // delay the worker's refreshes. canopycms-next wraps every plugin with `verifyTokenOnly`.
+    if (plugin instanceof CachingAuthPlugin)
+        return fetchFromPlugin(plugin, unique);
+    const cache = cacheFor(plugin);
+    const result = new Map();
+    const missing = [];
+    for (const id of unique) {
+        const hit = cache.get(id);
+        if (hit)
+            result.set(id, hit.user);
+        else
+            missing.push(id);
+    }
+    if (missing.length === 0)
+        return result;
+    const fetched = await fetchFromPlugin(plugin, missing);
+    for (const [id, user] of fetched) {
+        cache.set(id, { user });
+        result.set(id, user);
+    }
+    return result;
+}
+/** Every lookup answers with the same name the editor shows: blank or id-equal names become ''. */
+const withPersonName = (user) => user && { ...user, name: personName(user.id, user.name) ?? '' };
+async function fetchFromPlugin(plugin, ids) {
+    const result = new Map(ids.map((id) => [id, null]));
+    const getUsersMetadata = plugin.getUsersMetadata?.bind(plugin);
+    if (getUsersMetadata) {
+        for (let i = 0; i < ids.length; i += MAX_USER_METADATA_BATCH) {
+            const users = await getUsersMetadata(ids.slice(i, i + MAX_USER_METADATA_BATCH));
+            // A provider answering for an id nobody asked about must not plant it in the cache.
+            for (const user of users)
+                if (result.has(user.id))
+                    result.set(user.id, withPersonName(user));
+        }
+        return result;
+    }
+    let next = 0;
+    const worker = async () => {
+        while (next < ids.length) {
+            const id = ids[next++];
+            result.set(id, withPersonName(await plugin.getUserMetadata(id)));
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(SINGLE_LOOKUP_CONCURRENCY, ids.length) }, worker));
+    return result;
+}
+/** Matches the id bound `/users/batch` accepts; ids read from stored JSON are unvalidated. */
+const MAX_USER_ID_LENGTH = 256;
+/**
+ * The name and avatar of each id a response may show to any reader, never the email. Callers pass
+ * only ids the requester can already see. Non-string, empty, oversized, bot and anonymous ids are
+ * skipped: the editor labels bots and the anonymous user without a lookup. Unknown ids are absent.
+ */
+export async function lookupUserProfiles(plugin, ids) {
+    const wanted = new Set();
+    for (const id of ids) {
+        if (typeof id === 'string' &&
+            id.length > 0 &&
+            id.length <= MAX_USER_ID_LENGTH &&
+            id !== ANONYMOUS_USER.userId &&
+            !isSystemUserId(id)) {
+            wanted.add(id);
+        }
+    }
+    if (wanted.size === 0)
+        return [];
+    const found = await lookupUsersMetadata(plugin, [...wanted]);
+    const profiles = [];
+    // Built field by field: a provider's user record carries an email, which a profile never does.
+    for (const [id, user] of found) {
+        // A record for some other id (a provider resolving an alias) names someone nobody asked about.
+        if (user === null || user.id !== id)
+            continue;
+        profiles.push(user.avatarUrl === undefined
+            ? { id: user.id, name: user.name }
+            : { id: user.id, name: user.name, avatarUrl: user.avatarUrl });
+    }
+    return profiles;
+}

package/dist/authorization/branch.d.ts

@@ -50,7 +50,7 @@ export declare function createCheckBranchAccess(defaultAccess?: DefaultBranchAcc
 export interface WorkflowActionOptions {
     /**
      * When true, disables the system-branch grant below. The protected base
-     * branch is auto-provisioned with `createdBy: 'canopycms-system'`, which
+     * branch is auto-provisioned with `createdBy: SYSTEM_USER_ID`, which
      * would otherwise let anyone with general branch access submit/withdraw it
      * -- pass `getBranchProtection(...).isProtected` here so only
      * admins/reviewers/explicit-ACL users retain workflow rights on it.

package/dist/authorization/branch.js

@@ -1,5 +1,6 @@
-import { isAdmin, isReviewer } from './helpers.js';
+import { isAdmin, isLockedOutOfBranch, isReviewer } from './helpers.js';
 import { getBranchProtection } from './protected-branch.js';
+import { SYSTEM_USER_ID } from '../system-users.js';
 /**
  * Check if user has access to a branch with explicit default behavior.
  *
@@ -18,20 +19,18 @@ export function checkBranchAccessWithDefault(context, user, defaultAccess = 'den
         return { allowed: true, reason: 'privileged' };
     }
     const access = context.branch.access;
-    const hasUserConstraint = !!access.allowedUsers?.length;
-    const hasGroupConstraint = !!access.allowedGroups?.length;
-    const managerOrAdminAllowed = access.managerOrAdminAllowed ?? false;
-    if (!hasUserConstraint && !hasGroupConstraint && managerOrAdminAllowed) {
+    if (isLockedOutOfBranch(access, user.groups)) {
         return { allowed: false, reason: 'denied_by_acl' };
     }
+    const hasUserConstraint = !!access.allowedUsers?.length;
+    const hasGroupConstraint = !!access.allowedGroups?.length;
     if (!hasUserConstraint && !hasGroupConstraint) {
-        // The branch creator owns their own un-ACL'd branch, matching the three
-        // places that already grant on creator-ownership independently of branch
-        // access (listBranchesHandler, canDeleteBranch, canModifyBranchAccess):
-        // without it, under 'deny' a creator could delete their branch and rewrite
-        // its ACL but not read a file on it. Scoped to the no-ACL case on purpose --
-        // an EXPLICIT allowlist omitting the creator still denies them, which is how
-        // an admin locks down a branch someone else created.
+        // The branch creator owns their own un-ACL'd branch, as listBranchesHandler,
+        // canDeleteBranch and canModifyBranchAccess also grant: without it, under
+        // 'deny' a creator could delete their branch and rewrite its ACL but not
+        // read a file on it. Scoped to the no-ACL case on purpose -- an EXPLICIT
+        // allowlist omitting the creator still denies them, which is how an admin
+        // locks down a branch someone else created.
         if (context.branch.createdBy === user.userId) {
             return { allowed: true, reason: 'creator' };
         }
@@ -80,7 +79,7 @@ export function canPerformWorkflowAction(context, user, defaultAccess = 'deny',
         return false;
     }
     const userIsCreator = context.branch.createdBy === user.userId;
-    const isSystemBranch = !options?.isProtectedBranch && context.branch.createdBy === 'canopycms-system';
+    const isSystemBranch = !options?.isProtectedBranch && context.branch.createdBy === SYSTEM_USER_ID;
     return (userIsCreator ||
         accessResult.reason === 'privileged' ||
         accessResult.reason === 'allowed_by_acl' ||

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

@@ -15,21 +15,21 @@ export declare const GroupsFileSchema: z.ZodObject<{
         members: z.ZodArray<z.ZodType<string, z.ZodTypeDef, string>, "many">;
     }, "strip", z.ZodTypeAny, {
         name: string;
-        members: string[];
         id: string;
+        members: string[];
         description?: string | undefined;
     }, {
         name: string;
-        members: string[];
         id: string;
+        members: string[];
         description?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     updatedAt: string;
     groups: {
         name: string;
-        members: string[];
         id: string;
+        members: string[];
         description?: string | undefined;
     }[];
     updatedBy: string;
@@ -39,8 +39,8 @@ export declare const GroupsFileSchema: z.ZodObject<{
     updatedAt: string;
     groups: {
         name: string;
-        members: string[];
         id: string;
+        members: string[];
         description?: string | undefined;
     }[];
     updatedBy: string;

package/dist/authorization/helpers.d.ts

@@ -29,3 +29,11 @@ export declare function isAdmin(groups: readonly string[] | undefined): boolean;
 export declare function isReviewer(groups: readonly string[] | undefined): boolean;
 /** For operations that need elevated rights but not full admin. */
 export declare function isPrivileged(groups: readonly string[] | undefined): boolean;
+/**
+ * Whether a branch's `managerOrAdminAllowed` lockdown shuts this user out. The lockdown is a
+ * ceiling over everything else that grants branch access -- the ACL, the creator, the default --
+ * so only Admins and Reviewers pass it. Dependency-free, so the editor's gating shares it.
+ */
+export declare function isLockedOutOfBranch(access: {
+    managerOrAdminAllowed?: boolean;
+} | undefined, groups: readonly string[] | undefined): boolean;

package/dist/authorization/helpers.js

@@ -38,3 +38,11 @@ export function isReviewer(groups) {
 export function isPrivileged(groups) {
     return isReviewer(groups);
 }
+/**
+ * Whether a branch's `managerOrAdminAllowed` lockdown shuts this user out. The lockdown is a
+ * ceiling over everything else that grants branch access -- the ACL, the creator, the default --
+ * so only Admins and Reviewers pass it. Dependency-free, so the editor's gating shares it.
+ */
+export function isLockedOutOfBranch(access, groups) {
+    return (access?.managerOrAdminAllowed ?? false) && !isPrivileged(groups);
+}

package/dist/authorization/index.d.ts

@@ -9,7 +9,7 @@ export { checkContentAccess, createCheckContentAccess, createContentAccessChecke
 export { checkBranchAccessWithDefault, createCheckBranchAccess, canPerformWorkflowAction, } from './branch.js';
 export { getBranchProtection, getBranchWriteProtection, type BranchProtection, type BranchWriteProtection, } from './protected-branch.js';
 export { checkPathAccess, createCheckPathAccess, resolveDefaultPathAccess } from './path.js';
-export { RESERVED_GROUPS, type ReservedGroupId, isReservedGroup, stripReservedGroups, isAdmin, isReviewer, isPrivileged, } from './helpers.js';
+export { RESERVED_GROUPS, type ReservedGroupId, isReservedGroup, stripReservedGroups, isAdmin, isReviewer, isPrivileged, isLockedOutOfBranch, } from './helpers.js';
 export { PermissionsFileSchema, createDefaultPermissionsFile, type PermissionsFile, loadPermissionsFile, loadPathPermissions, mutatePermissionsFile, ensurePermissionsFile, } from './permissions/index.js';
 export { GroupsFileSchema, createDefaultGroupsFile, type GroupsFile, type InternalGroup, loadGroupsFile, loadInternalGroups, deriveInternalGroups, mutateGroupsFile, } from './groups/index.js';
 export { mutateSettingsJsonFile, SettingsFileConflictError, SettingsVersionConflictError, type MutateSettingsFileOptions, } from './settings-file-store.js';

package/dist/authorization/index.js

@@ -8,7 +8,7 @@ export { checkContentAccess, createCheckContentAccess, createContentAccessChecke
 export { checkBranchAccessWithDefault, createCheckBranchAccess, canPerformWorkflowAction, } from './branch.js';
 export { getBranchProtection, getBranchWriteProtection, } from './protected-branch.js';
 export { checkPathAccess, createCheckPathAccess, resolveDefaultPathAccess } from './path.js';
-export { RESERVED_GROUPS, isReservedGroup, stripReservedGroups, isAdmin, isReviewer, isPrivileged, } from './helpers.js';
+export { RESERVED_GROUPS, isReservedGroup, stripReservedGroups, isAdmin, isReviewer, isPrivileged, isLockedOutOfBranch, } from './helpers.js';
 export { PermissionsFileSchema, createDefaultPermissionsFile, loadPermissionsFile, loadPathPermissions, mutatePermissionsFile, ensurePermissionsFile, } from './permissions/index.js';
 export { GroupsFileSchema, createDefaultGroupsFile, loadGroupsFile, loadInternalGroups, deriveInternalGroups, mutateGroupsFile, } from './groups/index.js';
 export { mutateSettingsJsonFile, SettingsFileConflictError, SettingsVersionConflictError, } from './settings-file-store.js';

package/dist/authorization/protected-branch.d.ts

@@ -76,9 +76,10 @@ export declare function getBranchProtection(config: Pick<CanopyConfig, 'mode' |
  * branches-list wire flag and the editor.
  *
  * `status` is REQUIRED and admits `undefined` because a missing status must
- * FAIL CLOSED: `branch.json` is read with a bare `JSON.parse(...) as
- * BranchMetadataFile` (branch-metadata.ts), so it can be absent at runtime.
- * Required, not optional, so "argument omitted" and "file had no status" stay
- * distinguishable -- the safe answer differs.
+ * FAIL CLOSED. A branch.json without one never gets this far (its read
+ * boundary, branch-metadata-file.ts, rejects it as corrupt), but a status can
+ * still arrive unset from a context built anywhere else. Required, not
+ * optional, so "argument omitted" and "status unknown" stay distinguishable --
+ * the safe answer differs.
  */
 export declare function getBranchWriteProtection(config: Pick<CanopyConfig, 'mode' | 'defaultBaseBranch'>, branchName: string, recordedBaseBranch: string | undefined, status: BranchStatus | undefined): BranchWriteProtection;

package/dist/authorization/protected-branch.js

@@ -11,6 +11,7 @@
 // api/guards.ts → here), and paths/branch.ts drags node:fs into the graph,
 // which breaks adopters' production `next build`.
 import { sanitizeBranchName } from '../paths/branch-name.js';
+import { baseBranchOf } from '../utils/base-branch.js';
 /**
  * Whether `branchName` is the protected base branch for `config`.
  *
@@ -32,7 +33,7 @@ import { sanitizeBranchName } from '../paths/branch-name.js';
  */
 export function getBranchProtection(config, branchName, recordedBaseBranch) {
     const sanitizedName = sanitizeBranchName(branchName);
-    const isProtected = sanitizedName === sanitizeBranchName(config.defaultBaseBranch ?? 'main') ||
+    const isProtected = sanitizedName === sanitizeBranchName(baseBranchOf(config)) ||
         (recordedBaseBranch !== undefined && sanitizedName === sanitizeBranchName(recordedBaseBranch));
     return {
         isProtected,
@@ -47,10 +48,11 @@ export function getBranchProtection(config, branchName, recordedBaseBranch) {
  * branches-list wire flag and the editor.
  *
  * `status` is REQUIRED and admits `undefined` because a missing status must
- * FAIL CLOSED: `branch.json` is read with a bare `JSON.parse(...) as
- * BranchMetadataFile` (branch-metadata.ts), so it can be absent at runtime.
- * Required, not optional, so "argument omitted" and "file had no status" stay
- * distinguishable -- the safe answer differs.
+ * FAIL CLOSED. A branch.json without one never gets this far (its read
+ * boundary, branch-metadata-file.ts, rejects it as corrupt), but a status can
+ * still arrive unset from a context built anywhere else. Required, not
+ * optional, so "argument omitted" and "status unknown" stay distinguishable --
+ * the safe answer differs.
  */
 export function getBranchWriteProtection(config, branchName, recordedBaseBranch, status) {
     const protection = getBranchProtection(config, branchName, recordedBaseBranch);