@xemahq/kernel-contracts 0.33.0 → 0.34.0

package/src/principal/lib/app-invocation-identity.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import {
+  SubjectKind,
+  SubjectRefSchema,
+  type SubjectRef,
+} from '../../subject';
+
+/**
+ * The two ways an app invocation names its `actor`.
+ *
+ * `AppInvocationIdentity` is SUGAR over the `ExecutionPrincipal.actor` field —
+ * it resolves to exactly one `SubjectRef` (via `resolveInvocationActor`). It
+ * adds no authority of its own; it only says WHOSE authority the app is
+ * exercising.
+ *
+ * **`AsApp` is not a bypass.** A scheduled app runs as `executor = app:<id>`
+ * WITH `actor = app:<id>` — the app IS the actor, acting purely as itself. It
+ * must hold an explicit app role IN ITS OWN app to do anything; there is no
+ * ambient "the scheduler said so" authority. A scheduled job does NOT skip row
+ * policy and does NOT skip field policy. `AsApp` narrows the app to its own
+ * granted authority exactly like any other principal — running unattended buys
+ * it nothing that running on behalf of a user would not have to earn through the
+ * same `clampAuthority` intersection.
+ */
+export enum AppInvocationMode {
+  /** The app acts on behalf of a signed-in user; `actor` is that user. */
+  OnBehalfOfUser = 'on-behalf-of-user',
+  /** The app acts as itself (e.g. a schedule); `actor === executor === app:<id>`. */
+  AsApp = 'as-app',
+}
+
+export const AppInvocationModeSchema = z.nativeEnum(AppInvocationMode);
+
+/**
+ * `OnBehalfOfUser` — the app is exercising a specific user's authority. `user`
+ * becomes `ExecutionPrincipal.actor`; the app is the `executor`.
+ */
+export interface OnBehalfOfUserIdentity {
+  mode: AppInvocationMode.OnBehalfOfUser;
+  /** The signed-in subject whose authority the app exercises. */
+  user: SubjectRef;
+  /** The app doing the acting (becomes `executor`). */
+  appId: string;
+}
+
+/**
+ * `AsApp` — the app acts as itself. `actor` and `executor` are BOTH
+ * `app:<appId>`; see the `AppInvocationMode` docblock — this is not a bypass.
+ */
+export interface AsAppIdentity {
+  mode: AppInvocationMode.AsApp;
+  /** The app acting as its own actor and executor. */
+  appId: string;
+}
+
+export type AppInvocationIdentity = OnBehalfOfUserIdentity | AsAppIdentity;
+
+const onBehalfOfUserShape = z.object({
+  mode: z.literal(AppInvocationMode.OnBehalfOfUser),
+  user: SubjectRefSchema,
+  appId: z.string().min(1),
+});
+
+const asAppShape = z.object({
+  mode: z.literal(AppInvocationMode.AsApp),
+  appId: z.string().min(1),
+});
+
+export const OnBehalfOfUserIdentitySchema =
+  onBehalfOfUserShape as z.ZodType<OnBehalfOfUserIdentity>;
+
+export const AsAppIdentitySchema = asAppShape as z.ZodType<AsAppIdentity>;
+
+export const AppInvocationIdentitySchema = z.discriminatedUnion('mode', [
+  onBehalfOfUserShape,
+  asAppShape,
+]) as z.ZodType<AppInvocationIdentity>;
+
+/**
+ * Resolve an `AppInvocationIdentity` to the `ExecutionPrincipal.actor` it is
+ * sugar for. `OnBehalfOfUser` → the named user. `AsApp` → the app itself
+ * (`app:<appId>`), which is ALSO the executor — an app acting as itself has no
+ * elevated authority (see the `AppInvocationMode` docblock). Total over the
+ * closed union; a new mode is a compile error here, never a silent default.
+ */
+export function resolveInvocationActor(
+  identity: AppInvocationIdentity,
+): SubjectRef {
+  switch (identity.mode) {
+    case AppInvocationMode.OnBehalfOfUser:
+      return identity.user;
+    case AppInvocationMode.AsApp:
+      return { kind: SubjectKind.App, id: identity.appId };
+  }
+}

package/src/principal/lib/clamp-authority.ts

@@ -0,0 +1,64 @@
+import type { CapabilityRef } from '../../capability';
+
+/**
+ * `clampAuthority` — the delegation intersection rule (plan D6).
+ *
+ *   effective(P) = grants(P.executor) ∩ effective(P.actor)
+ *
+ * The effective authority of a principal is the INTERSECTION of what the
+ * executor is granted with what the actor already effectively holds. It is
+ * NEVER a union: a delegate can only ever NARROW authority, never widen it. An
+ * app can never do more than its caller.
+ *
+ * Structurally it cannot widen, and this is the load-bearing property: every
+ * element of the returned set is drawn from `executorGrants` AND must also be
+ * present in `actorEffective`, so the result is a subset of BOTH inputs
+ * (`clamp(A, B) ⊆ A` and `clamp(A, B) ⊆ B`). There is no code path that adds a
+ * ref present in only one operand.
+ *
+ * An EMPTY intersection is the default and correct outcome — not an error, not a
+ * signal to fall back to either operand. A principal whose executor shares no
+ * capability with its actor is authorized for nothing, and that denial is the
+ * whole point (it is THE test that must exist before the Wave 10 function
+ * sandbox: a delegate holding a capability its actor lacks is denied).
+ *
+ * Pure and side-effect free. Inputs are read-only sets of `CapabilityRef`; the
+ * result is a fresh set (the smaller operand is iterated for efficiency, but the
+ * membership rule is symmetric so the result is identical either way).
+ */
+export function clampAuthority(
+  executorGrants: ReadonlySet<CapabilityRef>,
+  actorEffective: ReadonlySet<CapabilityRef>,
+): Set<CapabilityRef> {
+  const [smaller, larger] =
+    executorGrants.size <= actorEffective.size
+      ? [executorGrants, actorEffective]
+      : [actorEffective, executorGrants];
+
+  const intersection = new Set<CapabilityRef>();
+  for (const ref of smaller) {
+    if (larger.has(ref)) {
+      intersection.add(ref);
+    }
+  }
+  return intersection;
+}
+
+/**
+ * Fold `clampAuthority` down a whole chain of authority sets, in order.
+ * `clampAuthorityChain([grants(executor), effective(actor), …])` reduces every
+ * operand by intersection, so ANY empty operand collapses the whole result to
+ * empty. Every operand narrows; none widens. An empty input array is itself an
+ * empty authority set (nothing to be authorized for) — never a wildcard.
+ */
+export function clampAuthorityChain(
+  authoritySets: ReadonlyArray<ReadonlySet<CapabilityRef>>,
+): Set<CapabilityRef> {
+  if (authoritySets.length === 0) {
+    return new Set<CapabilityRef>();
+  }
+  return authoritySets.reduce<Set<CapabilityRef>>(
+    (acc, next) => clampAuthority(acc, next),
+    new Set<CapabilityRef>(authoritySets[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>;