@xemahq/kernel-contracts 0.32.0 → 0.34.0

package/src/principal/lib/delegation-chain.ts

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+import { subjectRefToString, type SubjectRef } from '../../subject';
+import type { DelegationGrant } from './delegation-grant';
+
+/**
+ * Maximum number of hops permitted in a single delegation chain. Delegation is
+ * bounded: user → app → workflow → agent is the deepest legitimate path, so a
+ * chain of more than THREE grants is rejected outright. This is a hard cap, not
+ * a truncation point — an over-long chain is an error, never silently clipped.
+ */
+export const MAX_DELEGATION_DEPTH = 3;
+
+/**
+ * Closed set of delegation-chain validation failures. Every rejection carries a
+ * structured code so callers branch without string parsing.
+ */
+export enum DelegationErrorCode {
+  /** The chain has more hops than `MAX_DELEGATION_DEPTH`. */
+  ChainTooDeep = 'DELEGATION_CHAIN_TOO_DEEP',
+  /** A subject appears more than once across the chain — a delegation cycle. */
+  Cycle = 'DELEGATION_CHAIN_CYCLE',
+  /** Hop `i`'s `to` is not hop `i+1`'s `from` — the chain is not contiguous. */
+  Discontinuous = 'DELEGATION_CHAIN_DISCONTINUOUS',
+  /** The chain's first `from` is not the principal's `actor`. */
+  NotAnchoredAtActor = 'DELEGATION_CHAIN_NOT_ANCHORED_AT_ACTOR',
+  /** The chain's last `to` is not the principal's `executor`. */
+  NotAnchoredAtExecutor = 'DELEGATION_CHAIN_NOT_ANCHORED_AT_EXECUTOR',
+  /**
+   * The chain is empty but `actor` and `executor` differ. An empty chain is
+   * only valid for a self-acting principal (`actor === executor`, e.g. a
+   * scheduled `AsApp` app); claiming delegation with no hops is malformed.
+   */
+  EmptyChainMismatch = 'DELEGATION_CHAIN_EMPTY_MISMATCH',
+}
+
+export const DelegationErrorCodeSchema = z.nativeEnum(DelegationErrorCode);
+
+/**
+ * Structured, fail-fast error thrown by `resolveDelegationChain`. Never a
+ * warning, never a coercion — an invalid chain aborts resolution.
+ */
+export class DelegationChainError extends Error {
+  readonly code: DelegationErrorCode;
+
+  constructor(args: { code: DelegationErrorCode; message: string }) {
+    super(args.message);
+    this.name = 'DelegationChainError';
+    this.code = args.code;
+  }
+}
+
+function subjectsEqual(a: SubjectRef, b: SubjectRef): boolean {
+  return subjectRefToString(a) === subjectRefToString(b);
+}
+
+/**
+ * Validate a delegation chain against its principal's `actor`/`executor`
+ * endpoints and return the (frozen) chain when it is well-formed.
+ *
+ * Fail-fast — throws `DelegationChainError` on ANY of:
+ *
+ *  - a chain longer than `MAX_DELEGATION_DEPTH` (`ChainTooDeep`);
+ *  - a cycle: any subject appearing twice in the hop sequence (`Cycle`);
+ *  - a chain whose first `from` is not `actor` (`NotAnchoredAtActor`);
+ *  - a chain whose last `to` is not `executor` (`NotAnchoredAtExecutor`);
+ *  - a non-contiguous chain where hop i's `to` ≠ hop i+1's `from`
+ *    (`Discontinuous`);
+ *  - an empty chain when `actor` ≠ `executor` (`EmptyChainMismatch`).
+ *
+ * Cycles and over-depth are ERRORS, never truncations: the chain is rejected
+ * whole, never clipped to fit.
+ */
+export function resolveDelegationChain(args: {
+  actor: SubjectRef;
+  executor: SubjectRef;
+  chain: readonly DelegationGrant[];
+}): readonly DelegationGrant[] {
+  const { actor, executor, chain } = args;
+
+  // Empty chain: only a self-acting principal (actor === executor) may omit
+  // delegation. Anything else is a delegation claim with no proof.
+  if (chain.length === 0) {
+    if (!subjectsEqual(actor, executor)) {
+      throw new DelegationChainError({
+        code: DelegationErrorCode.EmptyChainMismatch,
+        message: `Empty delegation chain requires actor === executor, but actor "${subjectRefToString(
+          actor,
+        )}" ≠ executor "${subjectRefToString(executor)}".`,
+      });
+    }
+    return Object.freeze([]);
+  }
+
+  if (chain.length > MAX_DELEGATION_DEPTH) {
+    throw new DelegationChainError({
+      code: DelegationErrorCode.ChainTooDeep,
+      message: `Delegation chain has ${chain.length} hops; the maximum is ${MAX_DELEGATION_DEPTH}.`,
+    });
+  }
+
+  // Anchor: first from === actor, last to === executor.
+  if (!subjectsEqual(chain[0]!.from, actor)) {
+    throw new DelegationChainError({
+      code: DelegationErrorCode.NotAnchoredAtActor,
+      message: `Delegation chain must start at actor "${subjectRefToString(
+        actor,
+      )}", but its first hop starts at "${subjectRefToString(chain[0]!.from)}".`,
+    });
+  }
+  const last = chain[chain.length - 1]!;
+  if (!subjectsEqual(last.to, executor)) {
+    throw new DelegationChainError({
+      code: DelegationErrorCode.NotAnchoredAtExecutor,
+      message: `Delegation chain must end at executor "${subjectRefToString(
+        executor,
+      )}", but its last hop ends at "${subjectRefToString(last.to)}".`,
+    });
+  }
+
+  // Contiguity + cycle detection over the node sequence
+  // [from0, to0, to1, …, toN-1].
+  const seen = new Set<string>();
+  const firstKey = subjectRefToString(chain[0]!.from);
+  seen.add(firstKey);
+  for (let i = 0; i < chain.length; i += 1) {
+    if (i > 0 && !subjectsEqual(chain[i - 1]!.to, chain[i]!.from)) {
+      throw new DelegationChainError({
+        code: DelegationErrorCode.Discontinuous,
+        message: `Delegation chain is not contiguous at hop ${i}: previous "to" "${subjectRefToString(
+          chain[i - 1]!.to,
+        )}" ≠ this "from" "${subjectRefToString(chain[i]!.from)}".`,
+      });
+    }
+    const toKey = subjectRefToString(chain[i]!.to);
+    if (seen.has(toKey)) {
+      throw new DelegationChainError({
+        code: DelegationErrorCode.Cycle,
+        message: `Delegation chain contains a cycle: subject "${toKey}" appears more than once.`,
+      });
+    }
+    seen.add(toKey);
+  }
+
+  return Object.freeze([...chain]);
+}

package/src/principal/lib/delegation-grant.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { SubjectRefSchema, type SubjectRef } from '../../subject';
+
+/**
+ * `DelegationGrant` — one hop in a delegation chain. It records HOW authority
+ * moved from one subject to the next, so the PDP and the audit trail can prove
+ * the path an invocation took (user → app → workflow → agent → connector)
+ * rather than collapsing it to "the workflow service called a connector".
+ *
+ * Deliberately minimal — `{ from, to, grantedAt, reason? }` — and it does NOT
+ * carry a per-hop capability subset. Justification: effective authority is
+ * resolved by `clampAuthority` as `grants(executor) ∩ effective(actor)` from the
+ * authorization plane's grant tables keyed by SUBJECT, not from data embedded in
+ * the chain. A grant here is a PROVENANCE record (who handed authority to whom,
+ * when, and why), never a capability carrier — putting a capability set on the
+ * hop would duplicate the clamp responsibility and create a second, forgeable
+ * source of truth for "what may this delegate do". `grantedAt` (ISO-8601) plus
+ * an optional human `reason` is the whole audit payload a hop needs.
+ */
+export interface DelegationGrant {
+  /** The subject handing authority DOWN at this hop. */
+  from: SubjectRef;
+  /** The subject RECEIVING authority at this hop. */
+  to: SubjectRef;
+  /** ISO-8601 timestamp at which this hop was minted. */
+  grantedAt: string;
+  /** Optional human-readable rationale for the delegation (audit only). */
+  reason?: string;
+}
+
+export const DelegationGrantSchema = z.object({
+  from: SubjectRefSchema,
+  to: SubjectRefSchema,
+  grantedAt: z.string().datetime(),
+  reason: z.string().min(1).optional(),
+}) as z.ZodType<DelegationGrant>;

package/src/principal/lib/execution-principal.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import {
+  SubjectRefSchema,
+  TokenClassSchema,
+  type SubjectRef,
+  type TokenClass,
+} from '../../subject';
+import {
+  ExecutionEnvironmentRefSchema,
+  type ExecutionEnvironmentRef,
+} from '../../execution-environment';
+import { AppChannelSchema, type AppChannel } from '../../app-runtime';
+import { DelegationGrantSchema, type DelegationGrant } from './delegation-grant';
+
+/**
+ * `ExecutionPrincipal` — the SINGLE delegation contract (plan D5).
+ *
+ * The tree previously answered "who is acting, on whose behalf, with what
+ * authority" in six divergent coats: `SubjectKind`, `TokenClass`,
+ * `SubjectRef.actingFor`, delegated sessions, external subjects, anonymous
+ * sessions, and a PDP "delegation clamp". `ExecutionPrincipal` is the one
+ * answer. It SURVIVES the whole hop path user → app → workflow → agent →
+ * connector — if it did not, the audit trail would collapse to "the workflow
+ * service called a connector" and the PDP could not prove HOW authority was
+ * delegated.
+ *
+ * - `actor` is the ORIGINAL human or external subject whose authority is being
+ *   exercised. `executor` is what is actually running (app | workflow | agent |
+ *   service). Effective authority is `clampAuthority(grants(executor),
+ *   effective(actor))` — an intersection, never a union.
+ * - `delegationChain` records every hop; `resolveDelegationChain` bounds it to
+ *   `MAX_DELEGATION_DEPTH` and rejects cycles fail-fast.
+ * - `channel` (preview/live), `appId`, `releaseId`, `tenantId`, `purpose` are
+ *   the invocation-context fields the PDP and audit trail stamp; all optional
+ *   because not every principal is an app invocation.
+ */
+export interface ExecutionPrincipal {
+  /** The original human or external subject on whose behalf execution runs. */
+  actor: SubjectRef;
+  /** What is actually running: app | workflow | agent | service. */
+  executor: SubjectRef;
+  /** Ordered record of how authority moved from `actor` to `executor`. */
+  delegationChain: DelegationGrant[];
+  /** The minted token class carried by this invocation. */
+  tokenClass: TokenClass;
+  /** The permission-plane environment this invocation is tagged with. */
+  environment: ExecutionEnvironmentRef;
+  /** The single tenant org this invocation is fenced to. */
+  orgId: string;
+  /** The app being invoked, when this is an app invocation. */
+  appId?: string;
+  /** The pinned release of `appId`, when applicable. */
+  releaseId?: string;
+  /** Which definition + data the invocation sees (preview | live). */
+  channel?: AppChannel;
+  /** Sub-tenant scope within `orgId`, when the app is multi-tenant. */
+  tenantId?: string;
+  /** Free-form audit annotation of why this invocation is happening. */
+  purpose?: string;
+}
+
+export const ExecutionPrincipalSchema = z.object({
+  actor: SubjectRefSchema,
+  executor: SubjectRefSchema,
+  delegationChain: z.array(DelegationGrantSchema),
+  tokenClass: TokenClassSchema,
+  environment: ExecutionEnvironmentRefSchema,
+  orgId: z.string().min(1),
+  appId: z.string().min(1).optional(),
+  releaseId: z.string().min(1).optional(),
+  channel: AppChannelSchema.optional(),
+  tenantId: z.string().min(1).optional(),
+  purpose: z.string().min(1).optional(),
+}) as z.ZodType<ExecutionPrincipal>;