@mnstry/atelier 0.2.0-alpha.12 → 0.2.0-alpha.13

package/src/boundary/delegation.mjs

@@ -0,0 +1,396 @@
+import { spawnSync } from 'node:child_process'
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { canonicalize } from '../attestation/jcs.mjs'
+import { verifyDocument } from '../attestation/sign.mjs'
+import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
+
+// Owner-signed delegation of the local boundary actor check (FD-BOUND-1).
+// A delegation lets one declared operator pass the private-domain actor check
+// for named repositories and operations. It never changes ownership, audiences,
+// paths, content rules, promotion, push-content approval or publication.
+//
+// Guarantee: attribution integrity for a cooperating operator. The actor check
+// itself stays attribution-grade: an operator can still declare another actor
+// (--actor, MNSTRY_ATELIER_ACTOR), edit the policy or project configuration, or
+// control the process that runs the check. A delegation adds that an owner's
+// signed, current, host-anchored consent is recorded when someone else commits.
+//
+// Trust: the policy and the delegations document are operator-writable, so a
+// delegation is authority only when its signature verifies against an owner key
+// in the host file at a fixed path, owned by root in root-owned directories. That
+// file is also the only source of revocation. Each delegation binds the whole
+// policy (ext excluded), the managed repository set and each repository's root
+// commit, so it cannot be loosened in place or replayed into an independently
+// created repository. Forks sharing the root commit are not distinguished.
+// `ext` is accepted and never read.
+
+export const DELEGATION_SCHEMA = 'atelier-boundary-delegation@v1'
+export const DELEGATIONS_DOCUMENT_SCHEMA = 'atelier-boundary-delegations@v1'
+export const OWNER_KEYS_SCHEMA = 'atelier-boundary-owner-keys@v1'
+export const DELEGATION_OPERATIONS = Object.freeze(['boundary-check', 'pre-commit'])
+export const MAX_DELEGATION_SPAN_MS = 90 * 24 * 60 * 60 * 1000
+export const HOST_OWNER_KEYS_PATH = '/etc/atelier/boundary-owner-keys.json'
+
+const DELEGATION_KEYS = ['schema', 'id', 'owner', 'operator', 'repos', 'operations', 'notBefore', 'expiresAt', 'policyDigest', 'repoRoots', 'signature', 'ext']
+const VERSION_RE = /^1\.[0-9]+\.[0-9]+$/
+const ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/
+const REPO_RE = /^[a-z0-9][a-z0-9._-]*$/
+// Owner and operator ids are shown to the signing owner, so they are restricted
+// to printable identifiers: no control characters, spaces or lookalikes.
+export const DELEGATION_ACTOR_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
+const UTC_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/
+const COMMIT_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
+const JWK_X_RE = /^[A-Za-z0-9_-]{43}$/
+const OWNER_KEYS_MAX_BYTES = 64 * 1024
+const MAX_DELEGATIONS = 64
+const MAX_REPOS = 64
+const MAX_KEYS = 64
+const MAX_REVOKED = 1024
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+const boundedString = (value, max = 128) => typeof value === 'string' && value.length > 0 && value.length <= max
+// A time must be a real calendar instant that round-trips: 2026-02-31 is refused,
+// never rolled over to March.
+const timeOf = (value) => {
+  if (typeof value !== 'string' || !UTC_RE.test(value)) return Number.NaN
+  const ms = Date.parse(value)
+  if (Number.isNaN(ms)) return Number.NaN
+  const iso = new Date(ms).toISOString()
+  return iso === value || iso.replace(/\.000Z$/, 'Z') === value || iso.replace(/0*Z$/, 'Z').replace(/\.Z$/, 'Z') === value ? ms : Number.NaN
+}
+
+// `ext` is never read, so it is removed before hashing, but only at the
+// extension positions the schema declares. A repository or actor that happens
+// to be named `ext` is ordinary policy and stays bound.
+const dropExt = (value) => {
+  if (!isObject(value)) return value
+  const { ext, ...rest } = value
+  return rest
+}
+function withoutExt(policy) {
+  if (!isObject(policy)) return policy ?? null
+  const out = dropExt(policy)
+  const each = (map) => (isObject(map) ? Object.fromEntries(Object.entries(map).map(([key, item]) => [key, dropExt(item)])) : map)
+  if (Object.hasOwn(out, 'repos')) out.repos = each(out.repos)
+  if (Object.hasOwn(out, 'actors')) out.actors = each(out.actors)
+  if (Object.hasOwn(out, 'promotion')) out.promotion = dropExt(out.promotion)
+  if (Array.isArray(out.contentRules)) out.contentRules = out.contentRules.map(dropExt)
+  if (Array.isArray(out.contentRuleExceptions)) out.contentRuleExceptions = out.contentRuleExceptions.map(dropExt)
+  return out
+}
+
+const managedRepoNames = (project) => (project?.repos ?? []).filter((repo) => !repo.external).map((repo) => repo.name).sort()
+
+/**
+ * The digest a delegation binds: the whole boundary policy (ext excluded) and the
+ * project's managed repository names. Any later edit to them voids every
+ * delegation until the owner signs again. Other project configuration (repo
+ * access, graph settings, repository paths) is not bound.
+ */
+export function policyDigest(policy, project) {
+  const bound = { policy: withoutExt(policy), managedRepos: managedRepoNames(project) }
+  return `sha256:${crypto.createHash('sha256').update(canonicalize(bound), 'utf8').digest('hex')}`
+}
+
+/**
+ * The repository's identity: the lowest-sorting root commit of HEAD, ignoring
+ * replace refs, or null when it has none. Forks and histories built on the same
+ * root share it; independently created repositories do not.
+ */
+export function repoRootCommit(repoPath, { gitExecutable = 'git' } = {}) {
+  if (!repoPath) return null
+  const result = spawnSync(gitExecutable, ['--no-replace-objects', '-C', repoPath, 'rev-list', '--max-parents=0', 'HEAD', '--'], { encoding: 'utf8', env: sanitizedGitEnvironment() })
+  if (result.status !== 0) return null
+  const roots = result.stdout.split('\n').map((line) => line.trim()).filter((line) => COMMIT_RE.test(line)).sort()
+  return roots[0] ?? null
+}
+
+function repoPathFor(project, name) {
+  return (project?.repos ?? []).find((repo) => repo.name === name && !repo.external)?.path ?? null
+}
+
+function delegationErrors(item, at, { actors, repos }) {
+  if (!isObject(item)) return [`${at} must be an object`]
+  const errors = []
+  for (const key of Object.keys(item)) {
+    if (!DELEGATION_KEYS.includes(key)) errors.push(`${at} must not include additional property ${key}`)
+  }
+  if (item.ext != null && !isObject(item.ext)) errors.push(`${at}.ext must be an object`)
+  if (item.schema !== DELEGATION_SCHEMA) errors.push(`${at}.schema must be ${DELEGATION_SCHEMA}`)
+  if (typeof item.id !== 'string' || !ID_RE.test(item.id)) errors.push(`${at}.id is invalid`)
+  if (typeof item.owner !== 'string' || !DELEGATION_ACTOR_RE.test(item.owner) || !Object.hasOwn(actors, item.owner)) errors.push(`${at}.owner must be a declared actor with a plain identifier`)
+  if (typeof item.operator !== 'string' || !DELEGATION_ACTOR_RE.test(item.operator) || !Object.hasOwn(actors, item.operator)) errors.push(`${at}.operator must be a declared actor with a plain identifier`)
+  if (item.owner === item.operator) errors.push(`${at}.operator must differ from the owner`)
+  const repoNames = Array.isArray(item.repos) ? item.repos : []
+  if (!repoNames.length || repoNames.length > MAX_REPOS || new Set(repoNames).size !== repoNames.length) {
+    errors.push(`${at}.repos must be a non-empty list of at most ${MAX_REPOS} without duplicates`)
+  }
+  for (const name of repoNames) {
+    const repo = typeof name === 'string' && REPO_RE.test(name) && Object.hasOwn(repos, name) ? repos[name] : null
+    if (!repo || repo.kind !== 'private_domain') errors.push(`${at}.repos ${String(name)} must be a declared private_domain repo`)
+    else if (repo.ownerActor !== item.owner) errors.push(`${at}.repos ${name} is not owned by ${String(item.owner)}`)
+  }
+  const operations = Array.isArray(item.operations) ? item.operations : []
+  if (!operations.length || new Set(operations).size !== operations.length || operations.some((op) => !DELEGATION_OPERATIONS.includes(op))) {
+    errors.push(`${at}.operations must be a non-empty list of ${DELEGATION_OPERATIONS.join(', ')}`)
+  }
+  const notBefore = timeOf(item.notBefore)
+  const expiresAt = timeOf(item.expiresAt)
+  if (Number.isNaN(notBefore)) errors.push(`${at}.notBefore must be an RFC 3339 UTC time`)
+  if (Number.isNaN(expiresAt)) errors.push(`${at}.expiresAt must be an RFC 3339 UTC time`)
+  if (!Number.isNaN(notBefore) && !Number.isNaN(expiresAt) && !(expiresAt > notBefore && expiresAt - notBefore <= MAX_DELEGATION_SPAN_MS)) {
+    errors.push(`${at}.expiresAt must be after notBefore and at most 90 days later`)
+  }
+  if (typeof item.policyDigest !== 'string' || !DIGEST_RE.test(item.policyDigest)) errors.push(`${at}.policyDigest must be a sha256 digest`)
+  const roots = item.repoRoots
+  if (!isObject(roots) || Object.keys(roots).length !== repoNames.length ||
+      !repoNames.every((name) => typeof name === 'string' && Object.hasOwn(roots, name) && typeof roots[name] === 'string' && COMMIT_RE.test(roots[name]))) {
+    errors.push(`${at}.repoRoots must hold one root commit per listed repo`)
+  }
+  const signature = item.signature
+  if (!isObject(signature) || signature.algorithm !== 'ed25519' || !boundedString(signature.keyId) || !boundedString(signature.value, 512) ||
+      Object.keys(signature).some((key) => !['algorithm', 'keyId', 'value', 'ext'].includes(key))) {
+    errors.push(`${at}.signature must be an ed25519 signature; an unsigned delegation grants nothing`)
+  }
+  return errors
+}
+
+/** Errors for one delegation checked against a policy (used before signing). */
+export function validateDelegation(item, policy) {
+  return delegationErrors(item, 'delegation', { actors: isObject(policy?.actors) ? policy.actors : {}, repos: isObject(policy?.repos) ? policy.repos : {} })
+}
+
+/**
+ * Errors for a delegations document, checked against the boundary policy it
+ * delegates under. Delegations live in their own document beside the policy,
+ * so the policy contract is not widened.
+ */
+export function validateDelegationsDocument(doc, policy) {
+  if (!isObject(doc)) return ['delegations document must be a JSON object']
+  const errors = []
+  for (const key of Object.keys(doc)) {
+    if (!['schema', 'contractVersion', 'delegations', 'ext'].includes(key)) errors.push(`delegations document must not include additional property ${key}`)
+  }
+  if (doc.schema !== DELEGATIONS_DOCUMENT_SCHEMA) errors.push(`delegations document schema must be ${DELEGATIONS_DOCUMENT_SCHEMA}`)
+  if (doc.contractVersion != null && !(typeof doc.contractVersion === 'string' && VERSION_RE.test(doc.contractVersion))) errors.push('delegations document contractVersion must be a 1.x.y version')
+  if (doc.ext != null && !isObject(doc.ext)) errors.push('delegations document ext must be an object')
+  if (!Array.isArray(doc.delegations)) return [...errors, 'delegations document must list delegations']
+  if (doc.delegations.length > MAX_DELEGATIONS) errors.push(`delegations document lists more than ${MAX_DELEGATIONS} delegations`)
+  const context = { actors: isObject(policy?.actors) ? policy.actors : {}, repos: isObject(policy?.repos) ? policy.repos : {} }
+  const seen = new Set()
+  for (const [index, item] of doc.delegations.entries()) {
+    const at = `delegations[${index}]`
+    errors.push(...delegationErrors(item, at, context))
+    if (isObject(item) && typeof item.id === 'string') {
+      if (seen.has(item.id)) errors.push(`${at}.id ${item.id} is duplicated`)
+      seen.add(item.id)
+    }
+  }
+  return errors
+}
+
+function ownerKeysErrors(doc) {
+  if (!isObject(doc)) return ['owner keys must be a JSON object']
+  const errors = []
+  for (const key of Object.keys(doc)) {
+    if (!['schema', 'contractVersion', 'keys', 'revokedDelegations', 'ext'].includes(key)) errors.push(`owner keys must not include additional property ${key}`)
+  }
+  if (doc.schema !== OWNER_KEYS_SCHEMA) errors.push(`owner keys schema must be ${OWNER_KEYS_SCHEMA}`)
+  if (doc.contractVersion != null && !(typeof doc.contractVersion === 'string' && VERSION_RE.test(doc.contractVersion))) errors.push('owner keys contractVersion must be a 1.x.y version')
+  if (doc.ext != null && !isObject(doc.ext)) errors.push('owner keys ext must be an object')
+  if (!Array.isArray(doc.keys) || doc.keys.length > MAX_KEYS) errors.push(`owner keys must list at most ${MAX_KEYS} keys`)
+  const seen = new Set()
+  for (const [index, key] of (Array.isArray(doc.keys) ? doc.keys : []).entries()) {
+    if (!isObject(key) || Object.keys(key).some((name) => !['actorId', 'keyId', 'algorithm', 'publicKeyJwk', 'ext'].includes(name)) ||
+        (key.ext != null && !isObject(key.ext)) || !boundedString(key.actorId) || !boundedString(key.keyId) || key.algorithm !== 'ed25519' ||
+        !isObject(key.publicKeyJwk) || key.publicKeyJwk.kty !== 'OKP' || key.publicKeyJwk.crv !== 'Ed25519' ||
+        typeof key.publicKeyJwk.x !== 'string' || !JWK_X_RE.test(key.publicKeyJwk.x) || Object.hasOwn(key.publicKeyJwk, 'd')) {
+      errors.push(`owner keys keys[${index}] must be an ed25519 public key with actorId and keyId`)
+      continue
+    }
+    const identity = `${key.actorId}\u0000${key.keyId}`
+    if (seen.has(identity)) errors.push(`owner keys keys[${index}] duplicates ${key.actorId}/${key.keyId}`)
+    seen.add(identity)
+  }
+  const revoked = doc.revokedDelegations
+  if (revoked != null && (!Array.isArray(revoked) || revoked.length > MAX_REVOKED || new Set(revoked).size !== revoked.length ||
+      revoked.some((id) => typeof id !== 'string' || !ID_RE.test(id)))) {
+    errors.push('owner keys revokedDelegations must be a list of distinct delegation ids')
+  }
+  return errors
+}
+
+/** Normalize a host-supplied owner-keys document. The caller is the trusted host. */
+export function ownerKeysFromDocument(doc) {
+  const errors = ownerKeysErrors(doc)
+  if (errors.length) return { ok: false, reason: 'delegation-owner-keys-invalid', errors }
+  return { ok: true, keys: doc.keys, revoked: new Set(doc.revokedDelegations ?? []) }
+}
+
+/** The normalized form of a host `ownerKeys` value, re-validated. */
+function normalizedOwnerKeys(ownerKeys) {
+  if (!isObject(ownerKeys)) return null
+  if (ownerKeys.ok === false) return ownerKeys
+  if (ownerKeys.ok === true && Array.isArray(ownerKeys.keys) && ownerKeys.revoked instanceof Set) {
+    return ownerKeysFromDocument({ schema: OWNER_KEYS_SCHEMA, keys: ownerKeys.keys, revokedDelegations: [...ownerKeys.revoked] })
+  }
+  return ownerKeysFromDocument(ownerKeys)
+}
+
+/**
+ * Load the host owner-keys file. It is trusted only when it is a regular file
+ * owned by the trusted account (root), not group- or world-writable, opened
+ * without following links, and every directory above it is owned by that
+ * account (or root) and not group- or world-writable. The checks run on the open
+ * descriptor, which is also what is read. The current account must not be the
+ * trusted one. Windows is refused until an owner and DACL check exists.
+ */
+export function loadOwnerKeysFile(file = HOST_OWNER_KEYS_PATH, { platform = process.platform, trustedUid = 0, currentUid = process.getuid?.() } = {}) {
+  const untrusted = (detail) => ({ ok: false, reason: 'delegation-owner-keys-untrusted', errors: [detail] })
+  if (platform === 'win32') return untrusted('owner keys are not supported on Windows')
+  if (typeof currentUid !== 'number') return untrusted('the current account cannot be determined')
+  if (currentUid === 0) return untrusted('owner keys cannot be trusted for the root account')
+  if (currentUid === trustedUid) return untrusted('the current account must not own the owner keys')
+  const resolved = path.resolve(file)
+  let fd
+  try {
+    fd = fs.openSync(resolved, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0))
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { ok: false, reason: 'delegation-owner-key-missing', errors: ['owner keys file not found'] }
+    if (error?.code === 'ELOOP') return untrusted('owner keys file must not be a symlink')
+    return untrusted('owner keys file cannot be opened')
+  }
+  try {
+    const stat = fs.fstatSync(fd)
+    if (!stat.isFile()) return untrusted('owner keys file must be a regular file')
+    if (stat.size > OWNER_KEYS_MAX_BYTES) return untrusted('owner keys file is too large')
+    if (stat.uid !== trustedUid) return untrusted('owner keys file must be owned by the trusted account')
+    if ((stat.mode & 0o022) !== 0) return untrusted('owner keys file must not be group- or world-writable')
+    let real
+    try {
+      real = fs.realpathSync(resolved)
+      const named = fs.lstatSync(real)
+      if (named.dev !== stat.dev || named.ino !== stat.ino) return untrusted('owner keys file changed while it was checked')
+    } catch {
+      return untrusted('owner keys file changed while it was checked')
+    }
+    for (let dir = path.dirname(real); ; dir = path.dirname(dir)) {
+      let info
+      try {
+        info = fs.statSync(dir)
+      } catch {
+        return untrusted('owner keys file directories changed while they were checked')
+      }
+      if ((info.uid !== trustedUid && info.uid !== 0) || (info.mode & 0o022) !== 0) {
+        return untrusted('owner keys file must be in directories owned by the trusted account and not group- or world-writable')
+      }
+      if (path.dirname(dir) === dir) break
+    }
+    let doc
+    try {
+      doc = JSON.parse(fs.readFileSync(fd, 'utf8'))
+    } catch {
+      return { ok: false, reason: 'delegation-owner-keys-invalid', errors: ['owner keys file is not valid JSON'] }
+    }
+    return ownerKeysFromDocument(doc)
+  } finally {
+    fs.closeSync(fd)
+  }
+}
+
+/**
+ * Owner keys for a CLI check: only the host file at its fixed path. The command
+ * line and environment cannot choose another file, so the host's keys and
+ * revocations always apply. Returns null when the host has none.
+ */
+export function ownerKeysForCommand() {
+  return fs.existsSync(HOST_OWNER_KEYS_PATH) || isSymlink(HOST_OWNER_KEYS_PATH) ? loadOwnerKeysFile(HOST_OWNER_KEYS_PATH) : null
+}
+
+function isSymlink(file) {
+  try {
+    return fs.lstatSync(file).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+/** The delegations document beside a boundary policy file. */
+export function delegationsPathFor(policyPath) {
+  return path.join(path.dirname(policyPath), 'boundary-delegations.v1.json')
+}
+
+/** Read the delegations document beside the policy, if one exists. */
+export function loadDelegationsFile(file) {
+  if (!fs.existsSync(file)) return { present: false, document: null, errors: [] }
+  let document
+  try {
+    document = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch {
+    return { present: true, document: null, errors: ['delegations document is not valid JSON'] }
+  }
+  if (!isObject(document)) return { present: true, document: null, errors: ['delegations document must be a JSON object'] }
+  return { present: true, document, errors: [] }
+}
+
+/**
+ * Decide whether a delegation lets `actorId` pass the actor check for one
+ * repository and operation. Returns `{ applies: true, delegation }` or
+ * `{ applies: false, reason }`; it never widens anything else.
+ */
+export function resolveDelegation({ policy, project, delegations = [], repoName, repo, actorId, operation, ownerKeys = null, now = Date.now(), rootCommitOf = repoRootCommit }) {
+  const deny = (reason) => ({ applies: false, reason })
+  const all = Array.isArray(delegations) ? delegations.filter(isObject) : []
+  const forOperator = all.filter((item) => item.operator === actorId)
+  if (!forOperator.length) return deny('delegation-missing')
+  const forRepo = forOperator.filter((item) => Array.isArray(item.repos) && item.repos.includes(repoName))
+  const inScope = forRepo.filter((item) => Array.isArray(item.operations) && item.operations.includes(operation))
+  if (!inScope.length) return deny('delegation-scope')
+  if (inScope.length > 1) return deny('delegation-ambiguous')
+  const [delegation] = inScope
+  if (validateDelegation(delegation, policy).length || delegation.owner !== repo?.ownerActor) return deny('delegation-malformed')
+  const keys = normalizedOwnerKeys(ownerKeys)
+  if (!keys) return deny('delegation-owner-key-missing')
+  if (!keys.ok) return deny(keys.reason)
+  // The key must be registered for the delegation's owner, not merely present.
+  const key = keys.keys.find((item) => item.actorId === delegation.owner && item.keyId === delegation.signature.keyId)
+  if (!key) return deny('delegation-owner-key-missing')
+  if (!verifyDocument(delegation, { publicKey: key }).valid) return deny('delegation-signature-invalid')
+  if (keys.revoked.has(delegation.id)) return deny('delegation-revoked')
+  if (now < Date.parse(delegation.notBefore)) return deny('delegation-not-yet-valid')
+  if (now >= Date.parse(delegation.expiresAt)) return deny('delegation-expired')
+  if (delegation.policyDigest !== policyDigest(policy, project)) return deny('delegation-policy-changed')
+  for (const name of delegation.repos) {
+    if (rootCommitOf(repoPathFor(project, name)) !== delegation.repoRoots[name]) return deny('delegation-repository-changed')
+  }
+  return { applies: true, delegation }
+}
+
+/** The bound values a delegation must carry for this policy and project. */
+export function delegationBindings({ policy, project, repos, rootCommitOf = repoRootCommit }) {
+  return {
+    policyDigest: policyDigest(policy, project),
+    repoRoots: Object.fromEntries((Array.isArray(repos) ? repos : []).map((name) => [name, rootCommitOf(repoPathFor(project, name))])),
+  }
+}
+
+/** An unsigned delegation document for the owner to read and sign. */
+export function draftDelegation({ policy, project, id, owner, operator, repos, operations, notBefore, expiresAt, rootCommitOf = repoRootCommit }) {
+  const doc = {
+    schema: DELEGATION_SCHEMA,
+    id,
+    owner,
+    operator,
+    repos,
+    operations,
+    notBefore,
+    expiresAt,
+    ...delegationBindings({ policy, project, repos, rootCommitOf }),
+    signature: null,
+  }
+  const errors = validateDelegation({ ...doc, signature: { algorithm: 'ed25519', keyId: 'unsigned', value: 'unsigned' } }, policy)
+  return { ok: errors.length === 0, delegation: doc, errors }
+}

package/src/boundary/policy.mjs

@@ -15,6 +15,7 @@ import {
   validateContentRuleExceptions,
   validateContentRules,
 } from './content-rules.mjs'
+import { delegationsPathFor, loadDelegationsFile, ownerKeysForCommand, resolveDelegation, validateDelegationsDocument } from './delegation.mjs'
 
 export const BOUNDARY_POLICY_SCHEMA = 'mnstry.atelier-boundary-policy@v1'
 export const PROMOTE_EVENT_SCHEMA = 'git-promote-event@v1'
@@ -115,6 +116,12 @@ function unknownKeys(value, label, allowed) {
     .map((key) => `${label} must not include additional property ${key}`)
 }
 
+// The schema declares `ext` as a reserved extension container that consumers
+// must ignore. It is accepted, never read, and never carries authority.
+function extErrors(value, label) {
+  return value?.ext != null && !isObject(value.ext) ? [`${label}.ext must be an object`] : []
+}
+
 function validAudienceList(value, label, required = false) {
   if (value == null && !required) return []
   if (!Array.isArray(value)) return [`${label} must be a list`]
@@ -128,8 +135,12 @@ function validAudienceList(value, label, required = false) {
 export function validateBoundaryPolicy(policy, project = null) {
   const errors = []
   if (!isObject(policy)) return ['boundary policy must be a JSON object']
-  errors.push(...unknownKeys(policy, '/', new Set(['schema', 'mode', 'actors', 'repos', 'promotion', 'forbiddenPaths', 'contentRules', 'contentRuleExceptions', 'governanceLedgerPath'])))
+  errors.push(...unknownKeys(policy, '/', new Set(['schema', 'contractVersion', 'mode', 'actors', 'repos', 'promotion', 'forbiddenPaths', 'contentRules', 'contentRuleExceptions', 'governanceLedgerPath', 'ext'])))
   if (policy.schema !== BOUNDARY_POLICY_SCHEMA) errors.push(`schema must be ${BOUNDARY_POLICY_SCHEMA}`)
+  if (policy.contractVersion != null && !(typeof policy.contractVersion === 'string' && /^1\.[0-9]+\.[0-9]+$/.test(policy.contractVersion))) {
+    errors.push('contractVersion must be a 1.x.y version')
+  }
+  errors.push(...extErrors(policy, '/'))
   if (!VALID_BOUNDARY_MODES.has(policy.mode)) errors.push('mode must be strict or legacy-warning')
 
   const actors = policy.actors
@@ -138,7 +149,8 @@ export function validateBoundaryPolicy(policy, project = null) {
   if (!isObject(actors)) errors.push('actors must be an object')
   if (!isObject(repos)) errors.push('repos must be an object')
   if (policy.promotion != null && !isObject(policy.promotion)) errors.push('promotion must be an object')
-  errors.push(...unknownKeys(promotion, 'promotion', new Set(['requiresGitPromote', 'recordsPath'])))
+  errors.push(...unknownKeys(promotion, 'promotion', new Set(['requiresGitPromote', 'recordsPath', 'ext'])))
+  errors.push(...extErrors(promotion, 'promotion'))
   if (policy.forbiddenPaths != null && !Array.isArray(policy.forbiddenPaths)) errors.push('forbiddenPaths must be a list')
   if (policy.contentRules != null) errors.push(...validateContentRules(policy.contentRules))
   if (policy.contentRuleExceptions != null) {
@@ -153,11 +165,15 @@ export function validateBoundaryPolicy(policy, project = null) {
   }
 
   for (const [actorId, actor] of Object.entries(isObject(actors) ? actors : {})) {
-    errors.push(...unknownKeys(actor, `actors.${actorId}`, new Set(['githubLogin', 'gitEmails', 'privateDomainRepo'])))
+    errors.push(...unknownKeys(actor, `actors.${actorId}`, new Set(['githubLogin', 'gitEmails', 'privateDomainRepo', 'ext'])))
+    errors.push(...extErrors(actor, `actors.${actorId}`))
     if (!isObject(actor)) {
       errors.push(`actors.${actorId} must be an object`)
       continue
     }
+    // The schema types these fields; a non-string login would still match through String().
+    if (actor.githubLogin != null && typeof actor.githubLogin !== 'string') errors.push(`actors.${actorId}.githubLogin must be a string`)
+    if (actor.gitEmails != null && !Array.isArray(actor.gitEmails)) errors.push(`actors.${actorId}.gitEmails must be a list`)
     if (!firstString(actor.githubLogin) && !asArray(actor.gitEmails).length) {
       errors.push(`actors.${actorId} must declare githubLogin or gitEmails`)
     }
@@ -176,7 +192,8 @@ export function validateBoundaryPolicy(policy, project = null) {
   }
 
   for (const [repoName, repo] of Object.entries(isObject(repos) ? repos : {})) {
-    errors.push(...unknownKeys(repo, `repos.${repoName}`, new Set(['kind', 'ownerActor', 'readBoundary', 'allowedAudiences', 'forbiddenAudiences', 'autoCommit'])))
+    errors.push(...unknownKeys(repo, `repos.${repoName}`, new Set(['kind', 'ownerActor', 'readBoundary', 'allowedAudiences', 'forbiddenAudiences', 'autoCommit', 'ext'])))
+    errors.push(...extErrors(repo, `repos.${repoName}`))
     if (!isObject(repo)) {
       errors.push(`repos.${repoName} must be an object`)
       continue
@@ -306,7 +323,7 @@ function nodePlacementFindings({ node, policy }) {
   return findings
 }
 
-function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors }) {
+function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors, operation, delegations, ownerKeys, now }) {
   const findings = []
   const operatedRepos = new Set(managedRepos(project).map((repo) => repo.name))
   const ownedRepos = Object.entries(policy.repos ?? {}).filter(([name, repo]) =>
@@ -322,7 +339,20 @@ function actorFindings({ policy, project, actor, gitExecutable, allowNetworkActo
       findings.push(finding({ severity, code: 'private-domain-actor-unverified', repo: repoName,
         message: `${repoName}: could not verify local actor for private domain repo owned by ${repo.ownerActor}${current.reason ? ` (${current.reason})` : ''}` }))
     } else if (current.actorId !== repo.ownerActor) {
-      findings.push(finding({ severity, code: 'private-domain-actor-mismatch', repo: repoName, message: `${repoName}: private domain repo is owned by ${repo.ownerActor}, but current actor is ${current.actorId}` }))
+      // Only an owner-signed delegation, verified against a host-supplied key,
+      // changes this outcome, and only for its operator, repos and operation.
+      const delegated = resolveDelegation({ policy, project, delegations, repoName, repo, actorId: current.actorId, operation, ownerKeys, now })
+      if (delegated.applies) {
+        const { id, owner, expiresAt } = delegated.delegation
+        findings.push(finding({ severity: 'info', code: 'private-domain-delegated-operator', repo: repoName,
+          message: `${repoName}: ${current.actorId} operates under delegation ${id} from owner ${owner} until ${expiresAt}`,
+          details: { actorId: current.actorId, owner, delegationId: id, expiresAt, operation } }))
+      } else {
+        const note = delegated.reason === 'delegation-missing' ? '' : ` (${delegated.reason})`
+        findings.push(finding({ severity, code: 'private-domain-actor-mismatch', repo: repoName,
+          message: `${repoName}: private domain repo is owned by ${repo.ownerActor}, but current actor is ${current.actorId}${note}`,
+          details: { delegationReason: delegated.reason } }))
+      }
     }
   }
   return findings
@@ -635,7 +665,7 @@ function promotionFindings({ policy, project, graph }) {
   return findings
 }
 
-export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false, forceActorErrors = false } = {}) {
+export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnly = false, actor = null, gitExecutable = 'git', allowNetworkActorResolution = true, allowHistoryActorResolution = false, forceActorErrors = false, delegations = null, ownerKeys = null, now = Date.now() } = {}) {
   const validationErrors = validateBoundaryPolicy(policy, project)
   let graph = null
   const findings = validationErrors.map((message) => finding({ severity: 'error', code: 'boundary-policy-invalid', message }))
@@ -645,7 +675,14 @@ export function checkBoundaryPolicy({ project, policy, staged = false, stagedOnl
     for (const node of graph.nodes ?? []) findings.push(...nodePlacementFindings({ node, policy }))
     findings.push(...promotionFindings({ policy, project, graph }))
   }
-  findings.push(...actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors }))
+  // Delegations come from their own document, never from the policy. An invalid
+  // document is an error and grants nothing.
+  const delegationErrors = delegations == null ? [] : validateDelegationsDocument(delegations, policy)
+  findings.push(...delegationErrors.map((message) => finding({ severity: 'error', code: 'boundary-delegations-invalid', message })))
+  const delegationList = delegations != null && !delegationErrors.length ? delegations.delegations : []
+  // A staged check is the commit path (the installed pre-commit hook runs it).
+  const operation = staged ? 'pre-commit' : 'boundary-check'
+  findings.push(...actorFindings({ policy, project, actor, gitExecutable, allowNetworkActorResolution, allowHistoryActorResolution, forceActorErrors, operation, delegations: delegationList, ownerKeys, now }))
   if (staged) {
     const stagedPaths = stagedPathsForProject(project, { gitExecutable })
     findings.push(...forbiddenPathFindings({ policy, stagedPaths }))
@@ -673,9 +710,14 @@ export function runBoundaryCheckCommand(argv = process.argv.slice(2)) {
   const project = commandProject({ argv })
   const loaded = loadBoundaryPolicy(project)
   const missingFindings = loaded.errors?.map((message) => finding({ code: 'boundary-policy-missing', message })) ?? []
-  const report = loaded.ok
-    ? checkBoundaryPolicy({ project, policy: loaded.policy, staged, stagedOnly, actor: firstString(args.actor) })
+  const sidecar = loaded.ok ? loadDelegationsFile(delegationsPathFor(loaded.policyPath)) : { present: false, document: null, errors: [] }
+  const sidecarFindings = sidecar.errors.map((message) => finding({ code: 'boundary-delegations-invalid', message }))
+  // Owner keys are read only when a delegations document exists.
+  const ownerKeys = sidecar.present && sidecar.document ? ownerKeysForCommand() : null
+  let report = loaded.ok
+    ? checkBoundaryPolicy({ project, policy: loaded.policy, staged, stagedOnly, actor: firstString(args.actor), delegations: sidecar.document, ownerKeys })
     : { ok: false, mode: null, schema: BOUNDARY_POLICY_SCHEMA, graphCounts: null, findings: missingFindings, errors: missingFindings, warnings: [] }
+  if (sidecarFindings.length) report = { ...report, ok: false, findings: [...sidecarFindings, ...report.findings], errors: [...sidecarFindings, ...report.errors] }
 
   if (json) {
     console.log(JSON.stringify(report, null, 2))

package/src/build/git.mjs

@@ -0,0 +1,18 @@
+import { execFileSync } from 'node:child_process'
+import { bytesAt, workspaceRoot, digest } from '../capabilities/files.mjs'
+import { harnessRef } from '../harnesses/contracts.mjs'
+import { inspectBuild } from './ledger.mjs'
+
+// Read-only local adapter. A host still owns commands, writer custody and CI.
+export function prepareGitCandidate({ workspaceRoot: input, records, artifact, writer }) {
+  const root = workspaceRoot(input), state = inspectBuild(records)
+  if (!state.establishment) throw new Error('build objective missing')
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')))
+  const git = args => execFileSync('git', ['-C', root, ...args], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+  if (git(['status', '--porcelain', '--untracked-files=all'])) throw new Error('candidate requires clean repository sources')
+  const commit = git(['rev-parse', 'HEAD']), tree = git(['rev-parse', 'HEAD^{tree}'])
+  const artifactDigest = digest(bytesAt(root, artifact))
+  if (git(['rev-parse', 'HEAD']) !== commit || git(['status', '--porcelain', '--untracked-files=all']) || digest(bytesAt(root, artifact)) !== artifactDigest) throw new Error('candidate changed during capture')
+  return { data: { objective: harnessRef(state.establishment), repository: state.establishment.data.repository, commit, tree, artifactDigest, writer,
+    ...(state.candidate ? { supersedes: harnessRef(state.candidate) } : {}) }, artifact, assurance: 'local-bytes-and-git-observation; writer-is-caller-reported', authority: 'none' }
+}

package/src/build/index.mjs

@@ -0,0 +1,3 @@
+export { inspectBuild } from './ledger.mjs'
+export { prepareGitCandidate } from './git.mjs'
+export { buildReadiness, buildCoordinationProposal } from '../harnesses/exchange.mjs'