@bunbraco/core 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kineco
+
+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/NOTICE

@@ -0,0 +1,69 @@
+bunbraco
+Copyright (c) 2026 Kineco
+
+This product includes third-party software. bunbraco is an independent project.
+It is not affiliated with, endorsed by, or sponsored by Umbraco A/S, which owns
+the Umbraco trademark.
+
+There are three places third-party material is redistributed, rather than merely
+depended on:
+
+  @bunbraco/backoffice-dist   the built Umbraco backoffice and the browser
+                              packages bundled into it, produced by
+                              `bun run vendor:backoffice`
+  @bunbraco/backoffice-dist   three CSS files copied unmodified from the Umbraco
+                              client source tree
+  @bunbraco/contracts         the Umbraco Management API OpenAPI document,
+                              copied unmodified
+
+No Umbraco trademark is redistributed. The Umbraco wordmark, the "U" roundel
+favicon and the installer illustration are deliberately not carried in this
+repository: MIT grants copyright permission and says nothing about trademarks, so
+bunbraco's own marks are served at those paths instead. See `BRANDED_ASSETS` in
+`@bunbraco/backoffice-host`.
+
+The Umbraco backoffice
+----------------------
+@umbraco-cms/backoffice 18.2.0 — MIT — https://github.com/umbraco/Umbraco-CMS
+@umbraco-ui/uui 2.0.2 — MIT — https://github.com/umbraco/Umbraco.UI
+
+Static files from the Umbraco client source tree
+------------------------------------------------
+css/umb-css.css, css/rte-content.css, css/umbraco-blockgridlayout.css
+  — copied unmodified from Umbraco-CMS release-18.2.0 — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @bunbraco/backoffice-dist under `upstream-static/`.
+
+`rte-content.css` itself carries Tiptap's default editor styles, copied from
+tiptap v2.11.7 (MIT); the file records this in its own header.
+
+The Umbraco Management API contract
+-----------------------------------
+OpenApi.json — copied unmodified from Umbraco-CMS release-18.2.0
+  (src/Umbraco.Cms.Api.Management/OpenApi.json) — MIT
+  — https://github.com/umbraco/Umbraco-CMS
+Shipped in @bunbraco/contracts, which also ships the TypeScript types generated
+from it.
+
+Browser runtime dependencies bundled into the backoffice build
+--------------------------------------------------------------
+@heximal/expressions 0.1.5 — BSD-3-Clause
+@microsoft/signalr 10.0.11 — MIT
+@tiptap/* 3.31.3 — MIT
+diff 9.0.0 — BSD-3-Clause
+dompurify 3.4.16 — Apache-2.0, elected from "MPL-2.0 OR Apache-2.0"
+element-internals-polyfill 3.0.2 — MIT
+lit 3.3.3 — BSD-3-Clause
+luxon 3.7.2 — MIT
+marked 18.0.14 — MIT
+monaco-editor 0.57.0 — MIT
+rxjs 7.8.2 — Apache-2.0
+uuid 14.0.2 — MIT
+
+dompurify is offered under either licence; Apache-2.0 is elected here, so no
+MPL-2.0 obligation attaches to the copy bundled into the backoffice build. Of the
+Apache-2.0 packages above, none ships a NOTICE file of its own, so Apache-2.0
+section 4(d) adds nothing to this file.
+
+Each package's own licence text ships inside its npm distribution and applies
+unchanged to the copies bundled here.

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@bunbraco/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Domain model, entity keys and shared contracts for bunbraco. No I/O.",
+  "license": "MIT",
+  "author": "Kineco",
+  "homepage": "https://github.com/kineco-au/bunbraco-cms#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kineco-au/bunbraco-cms.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/kineco-au/bunbraco-cms/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api-paths.ts

@@ -0,0 +1,22 @@
+/**
+ * The paths the vendored client hard-codes.
+ *
+ * Umbraco's `UmbracoPath` moves the editor, not its API: the Management API is
+ * declared by the contract and the client's generated SDK calls it at
+ * `/umbraco/management/api/v1/...` however the backoffice is mounted. The two
+ * SignalR hubs are built the same way in the client's own source. So these stay
+ * put while `backOfficePath` moves the shell, the login page, the static assets
+ * and the SPA's own routes.
+ */
+export const MANAGEMENT_API_PREFIX = '/umbraco/management/api/'
+
+export const MANAGEMENT_API_PATH = `${MANAGEMENT_API_PREFIX}v1`
+
+/** `server-event.context.js`: `${serverURL}/umbraco/serverEventHub`. */
+export const SERVER_EVENT_HUB_PATH = '/umbraco/serverEventHub'
+
+/** `preview.context.js`: `${serverUrl}/umbraco/PreviewHub`. */
+export const PREVIEW_HUB_PATH = '/umbraco/PreviewHub'
+
+/** Where the editor is mounted unless a site overrides `backOfficePath`. */
+export const DEFAULT_BACKOFFICE_PATH = '/bunbraco'

package/src/content-types.ts

@@ -0,0 +1,157 @@
+/**
+ * The content-type aggregate: a content type plus its property groups, property
+ * types, compositions, allowed children and templates.
+ *
+ * Kept as one aggregate because the editor saves it as one document, and because
+ * the property set is only meaningful together with the compositions it inherits.
+ */
+export interface PropertyTypeModel {
+  key: string
+  alias: string
+  name: string
+  description: string | null
+  dataTypeKey: string
+  /** The group this property renders in, or null for the generic tab. */
+  containerKey: string | null
+  sortOrder: number
+  variesByCulture: boolean
+  variesBySegment: boolean
+  mandatory: boolean
+  mandatoryMessage: string | null
+  regEx: string | null
+  regExMessage: string | null
+  labelOnTop: boolean
+  /** The file's `since`, when written. */
+  sinceVersion?: string | null
+  /** Set when the element is not yet live on the reading node: the state it goes live in. */
+  pending?: { version: string; revision: string } | null
+  /** Member types only: shown to the member on their profile. */
+  memberCanView?: boolean
+  /** Member types only: editable by the member on their profile. */
+  memberCanEdit?: boolean
+  /** Member types only: hidden from users without sensitive-data access. */
+  isSensitive?: boolean
+}
+
+export interface PropertyGroupModel {
+  key: string
+  name: string | null
+  alias: string | null
+  /** 'Tab' or 'Group'; the wire format is a string. */
+  type: string
+  sortOrder: number
+  parentKey: string | null
+}
+
+export type CompositionType = 'Composition' | 'Inheritance'
+
+export interface CompositionModel {
+  contentTypeKey: string
+  compositionType: CompositionType
+}
+
+export interface AllowedChildModel {
+  contentTypeKey: string
+  sortOrder: number
+}
+
+export interface CleanupModel {
+  preventCleanup: boolean
+  keepAllVersionsNewerThanDays: number | null
+  keepLatestVersionPerDayForDays: number | null
+}
+
+export interface ContentTypeAggregate {
+  key: string
+  alias: string
+  name: string
+  description: string | null
+  icon: string
+  allowedAsRoot: boolean
+  variesByCulture: boolean
+  variesBySegment: boolean
+  isElement: boolean
+  allowedInLibrary: boolean
+  collectionKey: string | null
+  cleanup: CleanupModel
+  properties: PropertyTypeModel[]
+  containers: PropertyGroupModel[]
+  compositions: CompositionModel[]
+  allowedContentTypes: AllowedChildModel[]
+  allowedTemplateKeys: string[]
+  defaultTemplateKey: string | null
+  /** Folder placement in the tree, which is not the composition graph. */
+  parentKey: string | null
+  sinceVersion?: string | null
+  pending?: { version: string; revision: string } | null
+}
+
+/**
+ * Umbraco's system media types (`IsSystemMediaType`): always present, not
+ * deletable, alias fixed. Keys from its installer.
+ */
+export const SYSTEM_MEDIA_TYPE_KEYS: Readonly<Record<'Folder' | 'Image' | 'File', string>> = {
+  Folder: 'f38bd2d7-65d0-48e6-95dc-87ce06ec2d3d',
+  Image: 'cc07b313-0843-4aa8-bbda-871c8da728c8',
+  File: '4c52d8ab-54e6-40cd-999c-7a5f24903e4d',
+}
+
+export function isSystemMediaType(key: string): boolean {
+  return Object.values(SYSTEM_MEDIA_TYPE_KEYS).includes(key.toLowerCase())
+}
+
+/**
+ * Umbraco's one built-in member type, "Member", by the key its installer uses:
+ * always present, so a fresh install can create a member without a schema file.
+ */
+export const SYSTEM_MEMBER_TYPE_KEY = 'd59be02f-1df9-4228-aa1e-01917d806cda'
+
+export function isSystemMemberType(key: string): boolean {
+  return key.toLowerCase() === SYSTEM_MEMBER_TYPE_KEY
+}
+
+/** How the editor labels a pending element. */
+export function pendingLabel(until: { version: string }): string {
+  return `goes live in ${until.version}`
+}
+
+export interface DataTypeModel {
+  key: string
+  /** Schema files reference a data type by this; Umbraco itself has only key and name. */
+  alias: string | null
+  name: string
+  editorAlias: string
+  editorUiAlias: string | null
+  /** One of ValueStorageType. */
+  dbType: string
+  values: Array<{ alias: string; value: unknown }>
+  parentKey: string | null
+}
+
+export interface TemplateModel {
+  key: string
+  name: string
+  alias: string
+  content: string | null
+  /** Derived from `export const layout = '…'` in the view; the tree hangs children under it. */
+  masterKey?: string | null
+}
+
+/** One entry in a backoffice tree. */
+export interface TreeItem {
+  key: string
+  name: string
+  hasChildren: boolean
+  parentKey: string | null
+  icon: string | null
+  isFolder: boolean
+  isElement?: boolean
+  editorUiAlias?: string | null
+  /** The document type of a blueprint in the blueprint tree. */
+  contentTypeKey?: string | null
+}
+
+export interface Page<T> {
+  total: number
+  items: T[]
+}

package/src/documents.ts

@@ -0,0 +1,124 @@
+/**
+ * The document aggregate.
+ *
+ * Values are a flat list keyed by (alias, culture, segment), matching the wire
+ * format, because that is also how they are stored: one `property_data` row per
+ * combination.
+ */
+export interface DocumentValue {
+  alias: string
+  culture: string | null
+  segment: string | null
+  value: unknown
+  /** Present on responses so the editor knows which editor rendered the value. */
+  editorAlias?: string
+  /** The data type's configuration, on reads; converters that depend on it use it. */
+  config?: Record<string, unknown>
+}
+
+/**
+ * Per-culture state. `NotCreated` means the culture has no name yet;
+ * `PublishedPendingChanges` means the draft differs from what is published.
+ */
+export type VariantState =
+  | 'NotCreated'
+  | 'Draft'
+  | 'Published'
+  | 'PublishedPendingChanges'
+  | 'Trashed'
+
+export interface DocumentVariant {
+  culture: string | null
+  segment: string | null
+  name: string
+  state: VariantState
+  createDate: Date
+  updateDate: Date
+  publishDate: Date | null
+  /** When a scheduled publish of this variant will run. */
+  scheduledPublishDate?: Date | null
+  scheduledUnpublishDate?: Date | null
+}
+
+export interface DocumentAggregate {
+  key: string
+  contentTypeKey: string
+  contentTypeAlias: string
+  contentTypeIcon: string
+  /** The list view the type shows its children in, if any. */
+  contentTypeCollectionKey?: string | null
+  templateKey: string | null
+  parentKey: string | null
+  sortOrder: number
+  isTrashed: boolean
+  /** True when any culture is published. */
+  published: boolean
+  /** True when the draft differs from the published version. */
+  edited: boolean
+  values: DocumentValue[]
+  variants: DocumentVariant[]
+}
+
+/** One property that failed validation, in the terms the editor highlights. */
+export interface DocumentValidationError {
+  alias: string
+  culture: string | null
+  segment: string | null
+  messages: string[]
+}
+
+/** What the content tree shows for a document, beyond the generic tree item. */
+export interface DocumentTreeItem {
+  key: string
+  name: string
+  hasChildren: boolean
+  parentKey: string | null
+  contentTypeKey: string
+  contentTypeCollectionKey?: string | null
+  icon: string
+  isTrashed: boolean
+  createDate: Date
+  ancestorKeys: string[]
+  variants: Array<{ culture: string | null; name: string; state: VariantState }>
+}
+
+/**
+ * A row in the Library tree, which mixes folders and elements: a folder carries
+ * the name and nothing else, so `documentType` is reported as null and its single
+ * variant as `NotCreated` — the contract's own way of saying there is no content
+ * here.
+ */
+export interface ElementTreeItem extends DocumentTreeItem {
+  isFolder: boolean
+}
+
+export interface DocumentVersionSummary {
+  id: string
+  documentKey: string
+  versionDate: Date
+  /** The draft that is currently being edited. */
+  isCurrentDraft: boolean
+  isCurrentPublished: boolean
+  preventCleanup: boolean
+  userKey: string | null
+  culture: string | null
+  /** What made this version: a save, publish, rollback or schema migration. */
+  kind?: 'save' | 'publish' | 'rollback' | 'migrate'
+}
+
+/** A value keyed for lookup, so variance handling stays explicit. */
+export function valueKey(alias: string, culture: string | null, segment: string | null): string {
+  return `${alias}|${culture ?? ''}|${segment ?? ''}`
+}
+
+/**
+ * The culture a value belongs to, honouring the effective variance: a value sent
+ * with a culture for an invariant property is stored invariant, which is what
+ * keeps a type change from orphaning data.
+ */
+export function normaliseValueCulture(
+  culture: string | null,
+  propertyVariesByCulture: boolean,
+): string | null {
+  return propertyVariesByCulture ? culture : null
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export * from './api-paths.ts'
+export * from './content-types.ts'
+export * from './documents.ts'
+export * from './notifications.ts'
+export * from './object-types.ts'
+export * from './paging.ts'
+export * from './permissions.ts'
+export * from './problem-details.ts'
+export * from './property-values.ts'
+export * from './return-urls.ts'
+export * from './sections.ts'
+export * from './uploads.ts'
+export * from './users.ts'

package/src/notifications.ts

@@ -0,0 +1,28 @@
+/**
+ * The `Umb-Notifications` response header. Note the name: it is NOT
+ * `Umbraco-Notifications`. The backoffice reads it, renders toasts, and strips
+ * it. Umbraco never sets it on GET.
+ */
+export const NOTIFICATIONS_HEADER = 'Umb-Notifications'
+
+export type EventMessageType = 'Default' | 'Info' | 'Error' | 'Success' | 'Warning'
+
+export interface EventMessage {
+  message: string
+  category: string
+  type: EventMessageType
+}
+
+export function notificationsHeaderValue(messages: readonly EventMessage[]): string {
+  return JSON.stringify(messages)
+}
+
+export function applyNotifications(
+  headers: Headers,
+  method: string,
+  messages: readonly EventMessage[],
+): void {
+  if (method.toUpperCase() === 'GET') return
+  if (messages.length === 0) return
+  headers.set(NOTIFICATIONS_HEADER, notificationsHeaderValue(messages))
+}

package/src/object-types.ts

@@ -0,0 +1,122 @@
+/**
+ * Node object types.
+ *
+ * `node` is a universal polymorphic tree — documents, media, members, all content
+ * types, data types, templates and folders are rows in it — and this GUID is the
+ * discriminator. The values are Umbraco's, so SQL and documentation transfer
+ * even though the table names do not.
+ *
+ * Written lowercase deliberately: Postgres' `uuid` type normalises to lowercase
+ * on read while SQLite stores text verbatim, so everything that compares a uuid
+ * must agree on one case. `normaliseUuid` enforces it on the way in.
+ */
+export const ObjectTypes = {
+  SystemRoot: 'ea7d8624-4cfe-4578-a871-24aa946bf34d',
+  Document: 'c66ba18e-eaf3-4cff-8a22-41b16d66a972',
+  DocumentType: 'a2cb7800-f571-4787-9638-bc48539a0efb',
+  DocumentTypeContainer: '2f7a2769-6b0b-4468-90dd-af42d64f7f16',
+  DocumentBlueprint: '6ebef410-03aa-48cf-a792-e1c1cb087aca',
+  DocumentBlueprintContainer: 'a7eff71b-fa69-4552-93fc-038f7deee453',
+  ContentRecycleBin: '01bb7ff2-24dc-4c0c-95a2-c24ef72bbac8',
+  DataType: '30a2a501-1978-4ddb-a57b-f7efed43ba3c',
+  DataTypeContainer: '521231e3-8b37-469c-9f9d-51afc91feb7b',
+  Template: '6fbde604-4178-42ce-a10b-8a2600a2f07d',
+  Media: 'b796f64c-1f99-4ffb-b886-4bf4bc011a9c',
+  MediaType: '4ea4382b-2f5a-4c2b-9587-ae9b3cf3602e',
+  MediaTypeContainer: '42aef799-b288-4744-9b10-be144b73cdc4',
+  MediaRecycleBin: 'cf3d8e34-1c1c-41e9-ae56-878b57b32113',
+  ElementContainer: '2815b0cf-9706-499f-aa2a-8a4c7aef005d',
+  ElementRecycleBin: 'a1ee71eb-659c-4eee-bc97-6243e721cc0d',
+  Member: '39eb0f98-b348-42a1-8662-e7eb18487560',
+  MemberType: '9b5416fb-e72f-45a9-a07b-5a9a2709ce43',
+  MemberTypeContainer: '59ef5767-7223-4abc-b229-72821dc711b9',
+  MemberGroup: '366e63b9-880f-4e13-a61c-98069b029728',
+  Element: '3d7b623c-94b1-487d-8554-a46ec37568be',
+  Language: '6b05d05b-ec78-49be-a4e4-79e274f07a77',
+  RelationType: 'b1988fad-8675-4f47-915a-b3a602bc5d8d',
+  LockObject: '87a9f1ff-b1e4-4a25-babb-465a4a47ec41',
+} as const
+
+export type ObjectType = (typeof ObjectTypes)[keyof typeof ObjectTypes]
+
+/** The canonical form for a uuid anywhere in the system. */
+export function normaliseUuid(value: string): string {
+  return value.toLowerCase()
+}
+
+export function uuidEquals(a: string | null | undefined, b: string | null | undefined): boolean {
+  if (!a || !b) return false
+  return a.toLowerCase() === b.toLowerCase()
+}
+
+/**
+ * `umb://document/2ef0…` or a bare uuid, as a dashed lowercase key.
+ *
+ * The two spellings a stored value uses for a reference. It lives here rather
+ * than beside the value converters that first needed it because exporting a
+ * bundle reads the same references out of the same values, and `@bunbraco/transfer`
+ * must not depend on the renderer to do it.
+ */
+export function keyFromReference(reference: unknown): string | undefined {
+  if (typeof reference !== 'string') return undefined
+  const hex = reference
+    .replace(/^umb:\/\/[a-z-]+\//i, '')
+    .replaceAll('-', '')
+    .toLowerCase()
+  if (!/^[0-9a-f]{32}$/.test(hex)) return undefined
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+/** Fixed node ids, as Umbraco seeds them. */
+export const SystemNodes = {
+  Root: -1,
+  ContentRecycleBin: -20,
+  MediaRecycleBin: -21,
+  ElementRecycleBin: -22,
+} as const
+
+/** `ContentVariation` is a flags byte on both content types and property types. */
+export const ContentVariation = {
+  Nothing: 0,
+  Culture: 1,
+  Segment: 2,
+  CultureAndSegment: 3,
+} as const
+
+export function variationFlags(variesByCulture: boolean, variesBySegment: boolean): number {
+  return (variesByCulture ? 1 : 0) | (variesBySegment ? 2 : 0)
+}
+
+export const variesByCulture = (flags: number): boolean => (flags & 1) !== 0
+export const variesBySegment = (flags: number): boolean => (flags & 2) !== 0
+
+/**
+ * Effective variance is the intersection of the content type's and the property
+ * type's: a property varies by culture only if its type does too.
+ */
+export function effectiveVariation(contentTypeFlags: number, propertyTypeFlags: number): number {
+  return contentTypeFlags & propertyTypeFlags
+}
+
+/** `PropertyGroupType`: a tab is rendered as a top-level tab, a group as a fieldset. */
+export const PropertyGroupType = { Group: 0, Tab: 1 } as const
+
+/** How values are stored in `property_data`, chosen by the data type. */
+export const ValueStorageType = {
+  Ntext: 'Ntext',
+  Nvarchar: 'Nvarchar',
+  Integer: 'Integer',
+  Date: 'Date',
+  Decimal: 'Decimal',
+} as const
+
+export type ValueStorageTypeName = (typeof ValueStorageType)[keyof typeof ValueStorageType]
+
+/** The `property_data` column a storage type writes to. */
+export const STORAGE_COLUMN: Record<ValueStorageTypeName, string> = {
+  Ntext: 'text_value',
+  Nvarchar: 'varchar_value',
+  Integer: 'int_value',
+  Date: 'date_value',
+  Decimal: 'decimal_value',
+}

package/src/paging.ts

@@ -0,0 +1,27 @@
+/** Umbraco's universal paging envelope. `total` is int64 in the contract. */
+export interface PagedViewModel<T> {
+  total: number
+  items: T[]
+}
+
+export const DEFAULT_TAKE = 100
+
+export interface SkipTake {
+  skip: number
+  take: number
+}
+
+export type SkipTakeResult = { ok: true; value: SkipTake } | { ok: false }
+
+export function parseSkipTake(params: URLSearchParams, defaultTake = DEFAULT_TAKE): SkipTakeResult {
+  const skip = Number(params.get('skip') ?? 0)
+  const take = Number(params.get('take') ?? defaultTake)
+  if (!Number.isInteger(skip) || !Number.isInteger(take) || skip < 0 || take < 0)
+    return { ok: false }
+  if (take > 0 && skip % take !== 0) return { ok: false }
+  return { ok: true, value: { skip, take } }
+}
+
+export function paged<T>(items: T[], total: number): PagedViewModel<T> {
+  return { total, items }
+}

package/src/permissions.ts

@@ -0,0 +1,165 @@
+/**
+ * Permission verbs.
+ *
+ * Umbraco 18 replaced the old single-letter action codes with verbs of the form
+ * `Umb.<Entity>.<Action>`, stored one per row. Granular rows additionally carry a
+ * node key and a context discriminator, so one table serves both per-document
+ * ACLs and per-property field-level security.
+ */
+export const DocumentPermissions = {
+  Read: 'Umb.Document.Read',
+  Create: 'Umb.Document.Create',
+  Update: 'Umb.Document.Update',
+  Delete: 'Umb.Document.Delete',
+  Publish: 'Umb.Document.Publish',
+  Unpublish: 'Umb.Document.Unpublish',
+  Move: 'Umb.Document.Move',
+  Duplicate: 'Umb.Document.Duplicate',
+  Sort: 'Umb.Document.Sort',
+  Rollback: 'Umb.Document.Rollback',
+  Notifications: 'Umb.Document.Notifications',
+  Permissions: 'Umb.Document.Permissions',
+  CultureAndHostnames: 'Umb.Document.CultureAndHostnames',
+  PublicAccess: 'Umb.Document.PublicAccess',
+  CreateBlueprint: 'Umb.Document.CreateBlueprint',
+  PropertyValueRead: 'Umb.Document.PropertyValue.Read',
+  PropertyValueWrite: 'Umb.Document.PropertyValue.Write',
+  RecycleBinRestore: 'Umb.DocumentRecycleBin.Restore',
+} as const
+
+export type DocumentVerb = (typeof DocumentPermissions)[keyof typeof DocumentPermissions]
+
+/** The discriminator on a granular permission row. */
+export type PermissionContext = 'Document' | 'Element' | 'DocumentTypeProperty'
+
+export const ADMIN_GROUP_ALIAS = 'admin'
+
+/** The resolved permission set for a user, assembled from all their groups. */
+export interface UserPermissions {
+  isAdmin: boolean
+  /** Verbs granted regardless of node. */
+  global: ReadonlySet<string>
+  /** Verbs granted only on specific nodes, keyed by node key. */
+  granular: ReadonlyMap<string, ReadonlySet<string>>
+}
+
+/**
+ * Where a user may work in one tree: everywhere, or at and below the given
+ * nodes. Neither means no access at all, not even to the root.
+ */
+export interface StartNodes {
+  root: boolean
+  keys: readonly string[]
+}
+
+export const ROOT_ACCESS: StartNodes = { root: true, keys: [] }
+
+/**
+ * Umbraco's path access: with root access everything, the recycle bin
+ * included; otherwise a node at or below a start node, and never in the bin.
+ * `chain` is the node's ancestor keys then its own, root first.
+ */
+export function hasPathAccess(
+  start: StartNodes,
+  chain: readonly string[],
+  trashed: boolean,
+): boolean {
+  if (start.root) return true
+  if (trashed) return false
+  return start.keys.some((key) => chain.includes(key))
+}
+
+/** A start node's position: its ancestor keys then its own, root first; empty for the root. */
+export type StartNodePath = readonly string[]
+
+const within = (path: StartNodePath, ancestor: StartNodePath) =>
+  ancestor.length <= path.length && ancestor.every((key, i) => path[i] === key)
+
+/**
+ * Umbraco's `CombineStartNodes`: the groups' start nodes keep the topmost, the
+ * user's own keep the deepest, and each of the user's replaces any group start
+ * node above or below it. Callers leave out nodes that no longer exist or are
+ * in the recycle bin.
+ */
+export function combineStartNodes(
+  group: readonly StartNodePath[],
+  user: readonly StartNodePath[],
+): StartNodes {
+  let kept: StartNodePath[] = []
+  for (const path of group) {
+    if (kept.some((k) => within(path, k))) continue
+    kept = kept.filter((k) => !within(k, path))
+    kept.push(path)
+  }
+  let own: StartNodePath[] = []
+  for (const path of user) {
+    if (own.some((k) => within(k, path))) continue
+    own = own.filter((k) => !within(path, k))
+    own.push(path)
+  }
+  for (const path of own) {
+    kept = kept.filter((k) => !within(path, k) && !within(k, path))
+    kept.push(path)
+  }
+  return {
+    root: kept.some((path) => path.length === 0),
+    keys: kept.filter((path) => path.length > 0).map((path) => path[path.length - 1] as string),
+  }
+}
+
+/** One group's verbs: its defaults, and the nodes it sets explicitly (an empty list denies all). */
+export interface GroupGrant {
+  key: string
+  alias: string
+  defaults: readonly string[]
+  granular: ReadonlyMap<string, readonly string[]>
+}
+
+/**
+ * Umbraco's `HasAccessToSensitiveData`: membership of the Sensitive data group.
+ * Without it, values of member properties marked sensitive are withheld.
+ */
+export function hasAccessToSensitiveData(groups: ReadonlyArray<{ alias: string }>): boolean {
+  return groups.some((group) => group.alias === 'sensitiveData')
+}
+
+/**
+ * The verbs a user holds on a node, as Umbraco calculates them: for each group,
+ * the nearest node on the path (the node itself first) that the group sets
+ * explicitly replaces its defaults; the result is the union over groups.
+ * `chain` is the node's ancestor keys then its own, root first; empty for the
+ * root itself.
+ */
+export function permissionsForPath(
+  groups: readonly GroupGrant[],
+  chain: readonly string[],
+): Set<string> {
+  const verbs = new Set<string>()
+  for (const group of groups) {
+    let granted = group.defaults
+    for (let i = chain.length - 1; i >= 0; i--) {
+      const explicit = group.granular.get(chain[i] as string)
+      if (explicit) {
+        granted = explicit
+        break
+      }
+    }
+    for (const verb of granted) verbs.add(verb)
+  }
+  return verbs
+}
+
+/**
+ * An administrator bypasses the permission tables entirely, matching Umbraco:
+ * membership of the admin group is the check, not an exhaustive grant list.
+ */
+export function hasPermission(
+  permissions: UserPermissions,
+  verb: string,
+  nodeKey?: string,
+): boolean {
+  if (permissions.isAdmin) return true
+  if (permissions.global.has(verb)) return true
+  if (!nodeKey) return false
+  return permissions.granular.get(nodeKey)?.has(verb) === true
+}

package/src/problem-details.ts

@@ -0,0 +1,57 @@
+/**
+ * RFC 7807 Problem Details as Umbraco emits them: `type` is the literal string
+ * "Error", never a URI, plus Umbraco's own extension members.
+ */
+export interface ProblemDetails {
+  type: string
+  title: string
+  status: number
+  detail?: string
+  instance?: string
+  /** The domain operation status enum name, e.g. "NotFound". */
+  operationStatus?: string
+  /** Validation failures keyed by JSON path into the request model. */
+  errors?: Record<string, string[]>
+  invalidProperties?: string[]
+  failedBranchItems?: Array<{ id: string; operationStatus: string }>
+}
+
+export const PROBLEM_TYPE = 'Error'
+
+export function problemDetails(
+  init: Omit<ProblemDetails, 'type'> & { type?: string },
+): ProblemDetails {
+  return { type: PROBLEM_TYPE, ...init }
+}
+
+export function problemResponse(problem: ProblemDetails, headers?: HeadersInit): Response {
+  return new Response(JSON.stringify(problem), {
+    status: problem.status,
+    headers: { ...headers, 'content-type': 'application/problem+json; charset=utf-8' },
+  })
+}
+
+export const notFound = (title = 'Not Found', detail?: string) =>
+  problemDetails({ title, status: 404, detail, operationStatus: 'NotFound' })
+
+export const unauthorized = (detail = 'Authentication is required.') =>
+  problemDetails({ title: 'Unauthorized', status: 401, detail, operationStatus: 'Unauthorized' })
+
+export const notImplemented = (operationId: string) =>
+  problemDetails({
+    title: 'Not implemented',
+    status: 501,
+    detail: `Operation '${operationId}' is declared in the contract but not implemented yet.`,
+    operationStatus: 'NotImplemented',
+  })
+
+/**
+ * Umbraco rejects a skip that is not a multiple of take, and the backoffice
+ * relies on that contract when it pages.
+ */
+export const invalidSkipTake = () =>
+  problemDetails({
+    title: 'Invalid skip/take',
+    detail: 'Skip must be a multiple of take - i.e. skip = 10, take = 5',
+    status: 400,
+  })

package/src/property-values.ts

@@ -0,0 +1,129 @@
+/**
+ * Editor-specific value shapes. Structured editors store JSON text and hand the
+ * editor the parsed value, as Umbraco's value editors do; everything else is
+ * stored and returned as is.
+ */
+
+export const RICH_TEXT_EDITOR_ALIAS = 'Umbraco.RichText'
+export const UPLOAD_FIELD_EDITOR_ALIAS = 'Umbraco.UploadField'
+export const IMAGE_CROPPER_EDITOR_ALIAS = 'Umbraco.ImageCropper'
+
+/** Editors whose value names an uploaded file, and so may arrive with a temporary file. */
+export const FILE_VALUE_EDITORS: ReadonlySet<string> = new Set([
+  UPLOAD_FIELD_EDITOR_ALIAS,
+  IMAGE_CROPPER_EDITOR_ALIAS,
+])
+
+/** Editors whose values are objects or arrays, stored as JSON. */
+export const JSON_VALUE_EDITORS: ReadonlySet<string> = new Set([
+  RICH_TEXT_EDITOR_ALIAS,
+  'Umbraco.BlockList',
+  'Umbraco.BlockGrid',
+  'Umbraco.CheckBoxList',
+  'Umbraco.ColorPicker',
+  'Umbraco.DateTimeWithTimeZone',
+  'Umbraco.DropDown.Flexible',
+  // A `Guid[]` of the elements picked, not the `umb://…` references a content
+  // picker stores.
+  'Umbraco.ElementPicker',
+  'Umbraco.ImageCropper',
+  'Umbraco.MediaPicker3',
+  'Umbraco.MultipleTextstring',
+  'Umbraco.MultiUrlPicker',
+  'Umbraco.Slider',
+  'Umbraco.Tags',
+])
+
+export interface RichTextValue {
+  markup: string
+  blocks: unknown
+}
+
+function tryParse(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * A string spread into an object (`{...'abc'}` is `{0:'a',1:'b',2:'c'}`), which
+ * earlier builds stored when they handed the editor JSON text instead of JSON.
+ */
+function unspreadString(value: unknown): string | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
+  const entries = Object.entries(value as Record<string, unknown>)
+  const indexed = entries.filter(([key]) => /^\d+$/.test(key))
+  if (indexed.length === 0) return undefined
+  const chars: string[] = []
+  for (const [key, char] of indexed) {
+    if (typeof char !== 'string' || char.length !== 1) return undefined
+    chars[Number(key)] = char
+  }
+  if (chars.length !== indexed.length) return undefined
+  return chars.join('')
+}
+
+function toRichText(value: unknown): RichTextValue {
+  if (typeof value === 'string') {
+    const parsed = tryParse(value)
+    if (parsed && typeof parsed === 'object') return toRichText(parsed)
+    return { markup: value, blocks: null }
+  }
+  const spread = unspreadString(value)
+  if (spread !== undefined) return toRichText(spread)
+  const object = (value ?? {}) as Partial<RichTextValue>
+  return {
+    markup: typeof object.markup === 'string' ? object.markup : '',
+    blocks: object.blocks ?? null,
+  }
+}
+
+/**
+ * An upload is stored as its path (`/media/ab12cd34/file.pdf`), as Umbraco
+ * stores it, and edited as `{ src }`.
+ */
+function toUpload(stored: unknown): { src: string } | null {
+  if (typeof stored === 'string') {
+    const parsed = tryParse(stored)
+    if (parsed && typeof parsed === 'object') return toUpload(parsed)
+    return stored ? { src: stored } : null
+  }
+  const src = (stored as { src?: unknown } | null)?.src
+  return typeof src === 'string' && src ? { src } : null
+}
+
+/** A stored instant as the date pickers show it: `2026-01-02 03:04:05`, in the zone it was entered in. */
+function toWallClock(stored: unknown): unknown {
+  const date = new Date(String(stored))
+  if (Number.isNaN(date.getTime())) return stored
+  return date.toISOString().slice(0, 19).replace('T', ' ')
+}
+
+/** The value an editor receives for what is stored. */
+export function toEditorValue(editorAlias: string | undefined, stored: unknown): unknown {
+  if (stored === null || stored === undefined || !editorAlias) return stored
+  if (editorAlias === RICH_TEXT_EDITOR_ALIAS) return toRichText(stored)
+  if (editorAlias === UPLOAD_FIELD_EDITOR_ALIAS) return toUpload(stored)
+  if (editorAlias === 'Umbraco.TrueFalse')
+    return stored === true || stored === 1 || stored === '1' || stored === 'true'
+  if (editorAlias === 'Umbraco.DateTime') return toWallClock(stored)
+  if (!JSON_VALUE_EDITORS.has(editorAlias) || typeof stored !== 'string') return stored
+  const parsed = tryParse(stored)
+  return parsed !== null && typeof parsed === 'object' ? parsed : stored
+}
+
+/** The value a template receives: rich text is its markup, an upload its URL. */
+export function toPublishedValue(editorAlias: string | undefined, stored: unknown): unknown {
+  const value = toEditorValue(editorAlias, stored)
+  if (editorAlias === RICH_TEXT_EDITOR_ALIAS && value) return (value as RichTextValue).markup
+  if (editorAlias === UPLOAD_FIELD_EDITOR_ALIAS)
+    return (value as { src: string } | null)?.src ?? null
+  return value
+}
+
+/** What is stored for an upload the editor sent: its path, once any temporary file is placed. */
+export function toStoredUpload(value: unknown): string | null {
+  return toUpload(value)?.src ?? null
+}

package/src/return-urls.ts

@@ -0,0 +1,42 @@
+/** Validation for `returnUrl` values, which are attacker-supplied by nature. */
+
+/**
+ * The origin a candidate is resolved against. Any host but this one means the
+ * value escaped the site, whatever it looked like as text.
+ */
+const PROBE = 'https://return-url.invalid'
+
+/**
+ * A `returnUrl` reduced to a path on this site, or nothing.
+ *
+ * Both callers take the value from a query string and hand it to a browser to
+ * navigate to, so this is the difference between resuming a sign-in and bouncing
+ * the person somewhere else with a session in hand. Text comparisons are not
+ * enough: browsers read `\` as `/` and strip tabs and newlines before resolving,
+ * so `/\evil.com` and `/<tab>/evil.com` both leave the site while starting with a
+ * single slash. Resolving against a probe origin and insisting the result stayed
+ * there is the check that holds, and it rejects `javascript:` on the way through
+ * because that parses to no origin at all.
+ *
+ * The value returned is the re-serialised path, so what the caller stores cannot
+ * be read differently by whatever parses it next.
+ */
+export function localReturnUrl(value: string | null | undefined): string | undefined {
+  if (!value) return undefined
+  // By code point rather than a regex: a control character written into one is
+  // exactly what a linter is right to stop, and this says the same thing plainly.
+  const cleaned = [...value]
+    .filter((character) => {
+      const code = character.codePointAt(0) ?? 0
+      return code > 0x1f && code !== 0x7f
+    })
+    .join('')
+  if (!cleaned.startsWith('/')) return undefined
+  try {
+    const resolved = new URL(cleaned, PROBE)
+    if (resolved.origin !== PROBE) return undefined
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`
+  } catch {
+    return undefined
+  }
+}

package/src/sections.ts

@@ -0,0 +1,50 @@
+/**
+ * Sections, and the two different alias vocabularies for them.
+ *
+ * The database stores Umbraco's application aliases (`content`, `users`), while
+ * the backoffice matches section *manifest* aliases (`Umb.Section.Content`)
+ * against `allowedSections`. The Management API translates between them, so a
+ * value from one vocabulary must never leak into the other.
+ */
+export const SECTION_ALIASES = {
+  content: 'Umb.Section.Content',
+  media: 'Umb.Section.Media',
+  settings: 'Umb.Section.Settings',
+  users: 'Umb.Section.Users',
+  members: 'Umb.Section.Members',
+  translation: 'Umb.Section.Translation',
+  library: 'Umb.Section.Library',
+  packages: 'Umb.Section.Packages',
+} as const
+
+export type AppAlias = keyof typeof SECTION_ALIASES
+export type SectionAlias = (typeof SECTION_ALIASES)[AppAlias]
+
+/** Every section the shipped backoffice knows how to render. */
+export const CORE_SECTION_ALIASES: readonly SectionAlias[] = Object.values(SECTION_ALIASES)
+
+/**
+ * Translates stored application aliases into section manifest aliases, dropping
+ * any with no core section — `forms` is seeded by Umbraco but is a commercial
+ * add-on, so it has no section in the open-source backoffice.
+ */
+export function toSectionAliases(appAliases: readonly string[]): SectionAlias[] {
+  const seen = new Set<SectionAlias>()
+  for (const appAlias of appAliases) {
+    const sectionAlias = SECTION_ALIASES[appAlias as AppAlias]
+    if (sectionAlias) seen.add(sectionAlias)
+  }
+  return [...seen]
+}
+
+const STORED_ALIASES: Record<string, string> = { ...SECTION_ALIASES, forms: 'Umb.Section.Forms' }
+
+/** Umbraco's `SectionMapper.GetName`: a stored alias as its section alias, or unchanged when unknown. */
+export function sectionName(appAlias: string): string {
+  return STORED_ALIASES[appAlias] ?? appAlias
+}
+
+/** Umbraco's `SectionMapper.GetAlias`: a section alias as the alias stored for it, or unchanged. */
+export function sectionAppAlias(name: string): string {
+  return Object.entries(STORED_ALIASES).find(([, value]) => value === name)?.[0] ?? name
+}

package/src/uploads.ts

@@ -0,0 +1,41 @@
+/**
+ * What may be uploaded, as Umbraco's defaults have it (`ContentSettings`,
+ * `ContentImagingSettings`). The temporary-file configuration endpoint reports
+ * these, and the upload endpoints enforce the same lists.
+ */
+export interface UploadSettings {
+  /** Extensions treated as images: resizable, croppable, shown as thumbnails. */
+  imageFileTypes: string[]
+  /** Never accepted, whatever else is configured: files a server could execute. */
+  disallowedExtensions: string[]
+  /** When non-empty, only these are accepted. Empty means anything not disallowed. */
+  allowedExtensions: string[]
+  /** In bytes; null means no limit is configured. */
+  maxFileSize: number | null
+}
+
+export const DEFAULT_UPLOAD_SETTINGS: Readonly<UploadSettings> = {
+  imageFileTypes: ['jpeg', 'jpg', 'gif', 'bmp', 'png', 'tiff', 'tif', 'webp'],
+  disallowedExtensions: [
+    'ashx',
+    'aspx',
+    'ascx',
+    'config',
+    'cshtml',
+    'vbhtml',
+    'asmx',
+    'air',
+    'axd',
+    'xamlx',
+  ],
+  allowedExtensions: [],
+  maxFileSize: null,
+}
+
+/** Whether a file name's extension may be uploaded under these settings. */
+export function isUploadAllowed(fileName: string, settings: UploadSettings): boolean {
+  const dot = fileName.lastIndexOf('.')
+  const extension = dot >= 0 ? fileName.slice(dot + 1).toLowerCase() : ''
+  if (settings.disallowedExtensions.includes(extension)) return false
+  return settings.allowedExtensions.length === 0 || settings.allowedExtensions.includes(extension)
+}

package/src/users.ts

@@ -0,0 +1,51 @@
+/** Rules for backoffice users' credentials, as Umbraco's `UserPasswordConfigurationSettings` defaults them. */
+
+export interface PasswordConfiguration {
+  minimumPasswordLength: number
+  requireNonLetterOrDigit: boolean
+  requireDigit: boolean
+  requireLowercase: boolean
+  requireUppercase: boolean
+}
+
+export const DEFAULT_PASSWORD_CONFIGURATION: PasswordConfiguration = {
+  minimumPasswordLength: 10,
+  requireNonLetterOrDigit: false,
+  requireDigit: false,
+  requireLowercase: false,
+  requireUppercase: false,
+}
+
+export function isValidPassword(
+  password: string,
+  config: PasswordConfiguration = DEFAULT_PASSWORD_CONFIGURATION,
+): boolean {
+  if (password.length < config.minimumPasswordLength) return false
+  if (config.requireDigit && !/\d/.test(password)) return false
+  if (config.requireLowercase && !/[a-z]/.test(password)) return false
+  if (config.requireUppercase && !/[A-Z]/.test(password)) return false
+  if (config.requireNonLetterOrDigit && !/[^A-Za-z0-9]/.test(password)) return false
+  return true
+}
+
+/** A password that satisfies `config`, for a reset the backoffice shows once. */
+export function generateUserPassword(
+  config: PasswordConfiguration = DEFAULT_PASSWORD_CONFIGURATION,
+): string {
+  const letters = 'abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ'
+  const all = `${letters}23456789`
+  const length = Math.max(config.minimumPasswordLength, 12)
+  const random = crypto.getRandomValues(new Uint32Array(length))
+  const chars = Array.from(random, (n) => all[n % all.length] as string)
+  // One of each class keeps any combination of requirements satisfied
+  chars[0] = 'abcdefghijkmnopqrstuvwxyz'[(random[0] ?? 0) % 25] as string
+  chars[1] = 'ABCDEFGHJKLMNPQRSTUVWXYZ'[(random[1] ?? 0) % 24] as string
+  chars[2] = '23456789'[(random[2] ?? 0) % 8] as string
+  if (config.requireNonLetterOrDigit) chars[3] = '!@#$%*-_+='[(random[3] ?? 0) % 10] as string
+  return chars.join('')
+}
+
+/** A plausible e-mail address; Umbraco's check is no stricter. */
+export function isValidEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+$/.test(email)
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.