ZDDC/zddc/internal/zddc/special.go

package zddc

import (
	"path/filepath"
	"strings"
)

// SpecialFolderNames is the canonical list of folder names that drive
// per-tool availability rules and post-cascade access-decision behaviors.
// Centralized here so apps/availability and the access-control evaluator
// share one source of truth.
//
//   - "Incoming"  — vendor drop point; mkdir auto-ownership applies (creator
//                   becomes the new subtree's admin).
//   - "Working"   — internal pre-publication workspace; mkdir auto-ownership.
//   - "Staging"   — outbound transmittal staging; mkdir auto-ownership.
//   - "Issued"    — immutable archive of documents we sent out. WORM mask
//                   strips w/d/a from non-admin principals.
//   - "Received"  — immutable archive of documents we accepted. Same WORM
//                   semantics as Issued.
//
// Names are case-sensitive and exactly capitalized — operators name their
// folders this way by convention. A folder spelled differently (e.g.
// "incoming") is just a regular folder with no special semantics.
var SpecialFolderNames = []string{
	"Incoming",
	"Working",
	"Staging",
	"Issued",
	"Received",
}

// AutoOwnFolderNames is the subset of SpecialFolderNames where the file
// API's mkdir post-hook auto-writes a creator-owned .zddc into the new
// subdirectory. Issued / Received are deliberately excluded — filing in
// the immutable archive should not create owned subtrees inside it.
var AutoOwnFolderNames = []string{"Incoming", "Working", "Staging"}

// WormFolderNames is the subset of SpecialFolderNames covered by the
// post-cascade WORM mask. Any path whose chain crosses one of these
// names has w/d/a stripped from non-admin principals.
var WormFolderNames = []string{"Issued", "Received"}

// IsAutoOwnParent reports whether a folder named name should trigger
// the mkdir auto-ownership .zddc write when a child is created inside
// it. Used by the file API's mkdir handler.
func IsAutoOwnParent(name string) bool {
	for _, n := range AutoOwnFolderNames {
		if name == n {
			return true
		}
	}
	return false
}

// IsWormPath reports whether requestPath is inside an "Issued" or
// "Received" subtree. The check is purely on path segments — a file
// named "Issued.txt" does not trigger WORM, but
// "/Project/Vendor/Issued/foo.pdf" does, as does
// "/Project/Vendor/Issued/" itself. requestPath may be a URL path
// ("/foo/bar") or a filesystem path; only segment names matter.
func IsWormPath(requestPath string) bool {
	clean := strings.Trim(filepath.ToSlash(requestPath), "/")
	if clean == "" {
		return false
	}
	for _, seg := range strings.Split(clean, "/") {
		for _, name := range WormFolderNames {
			if seg == name {
				return true
			}
		}
	}
	return false
}

// WormMask reduces a verb set to the subset that survives the WORM
// constraint: the bitwise AND with VerbsRC. Removes w, d, and a.
//
// Callers apply this only when IsWormPath(path) is true AND the
// principal is NOT an admin (root admin or subtree admin) — admins
// are the deliberate escape hatch for mis-filed documents.
//
// The WORM mask is split-aware via WormFolderLevelIndex: grants
// inherited from ancestors above the Issued/Received folder are
// masked to read only ({r}), while grants at-or-below the WORM
// folder retain {r, c} so an operator can place a .zddc at the
// Issued folder explicitly granting `_doc_controller: cr`.
func WormMask(grant VerbSet) VerbSet { return grant & VerbsRC }

// WormFolderLevelIndex returns the chain index of the deepest
// "Issued" or "Received" segment in requestPath. The chain
// corresponds to the directory tree from root (index 0) to the
// requested directory; level i is the .zddc at path segment depth i.
//
// numLevels is len(chain.Levels); used to clamp results to the
// chain's actual range (e.g. a request to a file inside an Issued
// folder has a chain that only covers up to the Issued directory,
// not the file itself).
//
// Returns -1 if no WORM segment is in the request path or the
// computed index is out of range. The returned index satisfies
// 0 <= index < numLevels.
func WormFolderLevelIndex(requestPath string, numLevels int) int {
	clean := strings.Trim(filepath.ToSlash(requestPath), "/")
	if clean == "" || numLevels <= 0 {
		return -1
	}
	deepest := -1
	for i, seg := range strings.Split(clean, "/") {
		for _, name := range WormFolderNames {
			if seg == name {
				// URL segment i lives at chain index i+1 (root is index 0).
				idx := i + 1
				if idx < numLevels && idx > deepest {
					deepest = idx
				}
			}
		}
	}
	return deepest
}