@intentius/chant-lexicon-cedar 0.44.8

package/src/codegen/generate.ts

@@ -0,0 +1,123 @@
+/**
+ * Schema-driven code generation for the cedar lexicon (#1650).
+ *
+ * The pipeline is core's; what is unusual is its input. Every other lexicon
+ * fetches one global upstream spec, so `fetchSchemas` is an HTTP call and a
+ * cache. Cedar's spec-of-interest is the project's own `.cedarschema` (epic
+ * #1645), so `fetchSchemas` is a file read with a fallback, and the pinned
+ * upstream is the *grammar* — `@cedar-policy/cedar-wasm`, whose language
+ * version is asserted before anything is emitted.
+ *
+ * Order matters in {@link generate}: the language-version assert runs before
+ * the schema is resolved, because resolution is the thing whose output shape a
+ * grammar change would move.
+ */
+
+import { generatePipeline, writeGeneratedArtifacts } from "@intentius/chant/codegen/generate";
+import type { GenerateOptions, GenerateResult } from "@intentius/chant/codegen/generate";
+import type { NamingStrategy } from "@intentius/chant/codegen/naming";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { createNaming } from "./naming";
+import {
+  buildEmitModel,
+  generateRegistry,
+  generateRuntimeIndex,
+  generateTypes,
+  RUNTIME_TS,
+  type EmitModel,
+} from "./emit";
+import { DEFAULT_SCHEMA_KEY, fetchSchemas, resolveSchemaPath } from "../spec/fetch";
+import { parseCedarSchema, type CedarDecl } from "../spec/parse";
+import { assertPinnedLangVersion, assertPinnedSchema } from "../spec/pin";
+
+/** Filename of the generated registry. */
+export const LEXICON_JSON_FILENAME = "lexicon-cedar.json";
+
+export interface CedarGenerateOptions extends GenerateOptions {
+  /** Project root the `cedar.schema` path is resolved against. Defaults to `process.cwd()`. */
+  projectRoot?: string;
+  /** The `cedar` config namespace, when the caller has already loaded it. */
+  config?: { schema?: string; validation?: { requireProjectSchema?: boolean } };
+}
+
+/**
+ * Run the code generation pipeline.
+ */
+export async function generate(options: CedarGenerateOptions = {}): Promise<GenerateResult> {
+  // Refuse a grammar nobody chose before reading anything (#1390's rule).
+  assertPinnedLangVersion();
+
+  // The three emit callbacks each need the same model, and the pipeline hands
+  // them the results separately. Memoizing on the results array keeps one
+  // build per run without a mutable `let` whose assignment TypeScript cannot
+  // see happening inside a callback.
+  const models = new Map<readonly CedarDecl[], EmitModel>();
+  const modelFor = (results: CedarDecl[], naming: NamingStrategy): EmitModel => {
+    const cached = models.get(results);
+    if (cached) return cached;
+    const built = buildEmitModel(results, naming);
+    models.set(results, built);
+    return built;
+  };
+
+  const result = await generatePipeline<CedarDecl>(
+    {
+      fetchSchemas: () => fetchSchemas({ projectRoot: options.projectRoot, config: options.config }),
+
+      parseSchema: (typeName, data) => {
+        const { decls, resolved } = parseCedarSchema(data.toString("utf-8"));
+
+        // The content pin covers the schema this package ships, not a user's.
+        // Theirs is their input; its churn is theirs to own.
+        if (typeName === DEFAULT_SCHEMA_KEY) {
+          assertPinnedSchema(
+            resolved,
+            decls.map((d) => d.typeName).sort(),
+          );
+        }
+
+        return decls;
+      },
+
+      createNaming: (results) => createNaming(results),
+
+      generateRegistry: (results, naming) => generateRegistry(modelFor(results, naming)),
+
+      generateTypes: (results, naming) => generateTypes(modelFor(results, naming)),
+
+      generateRuntimeIndex: (results, naming) => generateRuntimeIndex(modelFor(results, naming)),
+
+      generateExtraArtifacts: () => ({ "runtime.ts": RUNTIME_TS }),
+    },
+    options,
+  );
+
+  if (options.verbose) {
+    const source = resolveSchemaPath({ projectRoot: options.projectRoot, config: options.config });
+    console.error(
+      `Generated ${result.resources} declaration(s) from ` +
+        `${source.isDefault ? "the bundled default schema" : source.path}`,
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Write generated files to the package directory.
+ */
+export function writeGeneratedFiles(result: GenerateResult, pkgDir?: string): void {
+  // This module lives at <pkg>/src/codegen/generate.ts, so the package root is
+  // three levels up — the scaffold's two-level default wrote into src/src/.
+  const dir = pkgDir ?? dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+  writeGeneratedArtifacts({
+    baseDir: dir,
+    files: {
+      [LEXICON_JSON_FILENAME]: result.lexiconJSON,
+      "index.d.ts": result.typesDTS,
+      "index.ts": result.indexTS,
+      ...(result.extraArtifacts ?? {}),
+    },
+  });
+}

package/src/codegen/naming.ts

@@ -0,0 +1,101 @@
+import { NamingStrategy, type NamingConfig, type NamingInput } from "@intentius/chant/codegen/naming";
+
+/**
+ * The name of the policy resource every generated bundle carries.
+ *
+ * It is not schema-derived — a Cedar schema declares entity types and actions,
+ * never policies — so it is claimed as a priority name before any schema type
+ * gets to contest a short name. A project whose schema declares its own
+ * `Policy` entity type therefore gets `AppPolicy` (or whatever its namespace
+ * is), and the authoring class keeps the name users import.
+ */
+export const POLICY_TS_NAME = "Policy";
+
+/** The `entityType` of the policy resource, matching the serializer. */
+export const POLICY_TYPE = "Cedar::Policy";
+
+/** `read` → `Read`; `service-account` → `ServiceAccount`. */
+export function pascalCase(value: string): string {
+  return value
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/** Split `App::Action::"read"` into its action id, or null for a non-action. */
+export function actionIdOf(typeName: string): string | null {
+  const match = /(?:^|::)Action::"(.*)"$/.exec(typeName);
+  return match ? match[1] : null;
+}
+
+/**
+ * Naming configuration for the cedar lexicon.
+ *
+ * Two shapes go through this rather than one: `App::User` (an entity type) and
+ * `App::Action::"read"` (an action). Both are entities in Cedar's model, so
+ * both are contested in the same pool — a schema with an entity type called
+ * `Read` and an action called `read` collides, and phase 4 qualifies the loser
+ * with its namespace rather than one silently overwriting the other.
+ */
+export const namingConfig: NamingConfig = {
+  priorityNames: {
+    [POLICY_TYPE]: POLICY_TS_NAME,
+  },
+
+  priorityAliases: {},
+
+  priorityPropertyAliases: {},
+
+  serviceAbbreviations: {},
+
+  /**
+   * Actions get an `Action` suffix. Without it `read`/`write`/`delete` become
+   * `Read`/`Write`/`Delete`, which read as entity types at the import site and
+   * collide with them in schemas that have both.
+   */
+  shortName: (typeName: string) => {
+    const actionId = actionIdOf(typeName);
+    if (actionId !== null) return `${pascalCase(actionId)}Action`;
+    return pascalCase(typeName.split("::").pop() ?? typeName);
+  },
+
+  /** The namespace — `App::User` → `App`, and the empty namespace → `Cedar`. */
+  serviceName: (typeName: string) => {
+    const segments = typeName.split("::");
+    return segments.length > 1 ? segments[0] : "Cedar";
+  },
+};
+
+/**
+ * Create a NamingStrategy instance from parsed results.
+ *
+ * `Cedar::Policy` is injected as an input because it has to be *in* the contest
+ * to win it: `priorityNames` is applied over the input type names, so a policy
+ * type that never appears there cannot claim `Policy` before a schema's own
+ * `Policy` entity type takes it in the short-name phase.
+ */
+export function createNaming(inputs: NamingInput[]): NamingStrategy {
+  return new NamingStrategy([{ typeName: POLICY_TYPE, propertyTypes: [] }, ...inputs], namingConfig);
+}
+
+/**
+ * The names derived from a primary name — the entity's attribute record and
+ * the action's context record.
+ *
+ * These are not contested by `NamingStrategy` (it only names the primary
+ * declarations), so they are de-duplicated against everything already taken.
+ * The suffix loop is deliberately boring: a schema that manages to collide
+ * `UserAttributes` twice gets `UserAttributes2`, which is ugly and correct,
+ * rather than one entry silently overwriting the other in the registry.
+ */
+export function deriveName(base: string, suffix: string, taken: Set<string>): string {
+  let candidate = `${base}${suffix}`;
+  let n = 2;
+  while (taken.has(candidate)) {
+    candidate = `${base}${suffix}${n}`;
+    n++;
+  }
+  taken.add(candidate);
+  return candidate;
+}

package/src/codegen/package.ts

@@ -0,0 +1,52 @@
+/**
+ * Cedar lexicon packaging — delegates to core's packagePipeline.
+ */
+
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import {
+  packagePipeline,
+  type PackageOptions,
+  type PackageResult,
+} from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+
+export type { PackageOptions, PackageResult };
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/**
+ * Package the Cedar lexicon into a distributable BundleSpec.
+ */
+export async function packageLexicon(opts: PackageOptions = {}): Promise<PackageResult> {
+  const pkgJson = JSON.parse(readFileSync(join(pkgDir, "..", "package.json"), "utf-8")) as {
+    version?: string;
+  };
+
+  return packagePipeline(
+    {
+      // Codegen reads this package's own directory as the project root, so
+      // bundling produces the default-schema surface no matter where the
+      // command is run from (#1650).
+      generate: (genOpts) => generate({ ...genOpts, projectRoot: pkgDir }),
+
+      buildManifest: () => ({
+        name: "cedar",
+        version: pkgJson.version ?? "0.0.0",
+        chantVersion: ">=0.1.0",
+        namespace: "Cedar",
+        intrinsics: [],
+        pseudoParameters: {},
+      }),
+
+      srcDir: pkgDir,
+
+      // Skills, initTemplates and the docs site are #1654.
+      collectSkills: () => new Map(),
+
+      version: pkgJson.version ?? "0.0.0",
+    },
+    opts,
+  );
+}

package/src/composites/composites.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Props, types and defaults for the two composites — plus the thing that
+ * matters more: what they serialize to, checked against cedar-wasm.
+ *
+ * A composite that produces the right `props` object and the wrong Cedar text
+ * is still broken, and the serializer is the only place the two meet.
+ */
+
+import { describe, expect, it } from "vitest";
+import { checkParsePolicySet, getValidRequestEnvsPolicy } from "@cedar-policy/cedar-wasm/nodejs";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import type { Declarable } from "@intentius/chant/declarable";
+import { DenyByDefaultSet, OwnerCanManage } from "./index";
+import { cedarSerializer } from "../serializer";
+import { DeleteAction, ReadAction, WriteAction } from "../generated/index";
+
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+const schema = readFileSync(join(pkgDir, "src", "spec", "default-schema.cedarschema"), "utf-8");
+
+function props(entity: Declarable): Record<string, unknown> {
+  return (entity as unknown as { props: Record<string, unknown> }).props;
+}
+
+/** Serialize a named set of policies to `.cedar` text. */
+function emit(entities: Record<string, Declarable>): string {
+  const map = new Map<string, Declarable>(Object.entries(entities));
+  const result = cedarSerializer.serialize(map);
+  return typeof result === "string" ? result : result.primary;
+}
+
+describe("OwnerCanManage", () => {
+  it("pins the resource scope and the ownership guard together", () => {
+    const p = props(OwnerCanManage({ entityType: "App::Document", actions: ReadAction }));
+
+    expect(p.effect).toBe("permit");
+    expect(p.resource).toEqual({ is: "App::Document" });
+    expect(p.when).toEqual(["resource.owner == principal"]);
+  });
+
+  it("defaults the owner attribute to `owner` and takes an override", () => {
+    expect(props(OwnerCanManage({ entityType: "App::Folder" })).when).toEqual([
+      "resource.owner == principal",
+    ]);
+
+    expect(
+      props(OwnerCanManage({ entityType: "App::Folder", ownerAttribute: "custodian" })).when,
+    ).toEqual(["resource.custodian == principal"]);
+  });
+
+  it("emits `==` for one action and `in` for several", () => {
+    expect(props(OwnerCanManage({ entityType: "App::Document", actions: ReadAction })).action).toEqual({
+      eq: ReadAction,
+    });
+    expect(props(OwnerCanManage({ entityType: "App::Document", actions: [ReadAction] })).action).toEqual({
+      eq: ReadAction,
+    });
+    expect(
+      props(OwnerCanManage({ entityType: "App::Document", actions: [ReadAction, WriteAction] })).action,
+    ).toEqual({ in: [ReadAction, WriteAction] });
+  });
+
+  it("leaves the action position unconstrained only when actions are omitted", () => {
+    expect(props(OwnerCanManage({ entityType: "App::Document" })).action).toEqual({});
+  });
+
+  it("widens the principal to anyone by default and narrows on request", () => {
+    expect(props(OwnerCanManage({ entityType: "App::Document" })).principal).toEqual({});
+    expect(props(OwnerCanManage({ entityType: "App::Document", principal: "App::User" })).principal).toEqual({
+      is: "App::User",
+    });
+    expect(
+      props(OwnerCanManage({ entityType: "App::Document", principal: { eq: 'App::User::"root"' } })).principal,
+    ).toEqual({ eq: 'App::User::"root"' });
+  });
+
+  it("appends extra guards after the ownership test", () => {
+    const p = props(
+      OwnerCanManage({
+        entityType: "App::Document",
+        actions: WriteAction,
+        when: ["context.mfa == true"],
+        unless: ['resource.classification == "confidential"'],
+      }),
+    );
+
+    expect(p.when).toEqual(["resource.owner == principal", "context.mfa == true"]);
+    expect(p.unless).toEqual(['resource.classification == "confidential"']);
+  });
+
+  it("omits `unless` entirely when none is asked for", () => {
+    expect("unless" in props(OwnerCanManage({ entityType: "App::Document" }))).toBe(false);
+  });
+
+  it("annotates its provenance and lets the caller override the id", () => {
+    const p = props(
+      OwnerCanManage({ entityType: "App::Document", annotations: { id: "doc-owner", team: "docs" } }),
+    );
+
+    expect(p.annotations).toEqual({
+      composite: "OwnerCanManage",
+      scopedTo: "App::Document",
+      id: "doc-owner",
+      team: "docs",
+    });
+  });
+
+  it("serializes to Cedar that parses and resolves to the intended envelope", () => {
+    const text = emit({
+      docOwnerRead: OwnerCanManage({
+        entityType: "App::Document",
+        actions: [ReadAction, WriteAction],
+        principal: "App::User",
+      }),
+    });
+
+    expect(text).toContain("permit (");
+    expect(text).toContain("resource is App::Document");
+    expect(checkParsePolicySet({ staticPolicies: text }).type).toBe("success");
+
+    const envs = getValidRequestEnvsPolicy(text.trim(), schema);
+    expect(envs.type).toBe("success");
+    if (envs.type === "success") {
+      expect(envs.principals).toEqual(["App::User"]);
+      expect(envs.resources).toEqual(["App::Document"]);
+      expect(envs.actions.sort()).toEqual([ReadAction, WriteAction].sort());
+    }
+  });
+});
+
+describe("DenyByDefaultSet", () => {
+  const member = OwnerCanManage({ entityType: "App::Document", actions: ReadAction });
+
+  it("returns the floor first, the members unchanged, and both in `all`", () => {
+    const set = DenyByDefaultSet({
+      policies: [member],
+      entityType: "App::Document",
+      when: ['resource.classification == "secret"'],
+    });
+
+    expect(props(set.floor).effect).toBe("forbid");
+    expect(set.members).toEqual([member]);
+    expect(set.all[0]).toBe(set.floor);
+    expect(set.all).toHaveLength(2);
+  });
+
+  it("does not mutate the caller's array", () => {
+    const policies = [member];
+    const set = DenyByDefaultSet({ policies, when: ["context.mfa == false"] });
+
+    expect(set.members).not.toBe(policies);
+    expect(policies).toHaveLength(1);
+  });
+
+  it("defaults both the resource and the action position to unconstrained", () => {
+    const p = props(DenyByDefaultSet({ policies: [], when: ["context.mfa == false"] }).floor);
+
+    expect(p.resource).toEqual({});
+    expect(p.action).toEqual({});
+    expect(p.principal).toEqual({});
+  });
+
+  it("narrows on entityType, actions and principal", () => {
+    const p = props(
+      DenyByDefaultSet({
+        policies: [],
+        entityType: "App::Document",
+        actions: [DeleteAction, WriteAction],
+        principal: "App::User",
+        when: ['resource.classification == "confidential"'],
+        unless: ['principal == App::User::"archivist"'],
+      }).floor,
+    );
+
+    expect(p.resource).toEqual({ is: "App::Document" });
+    expect(p.action).toEqual({ in: [DeleteAction, WriteAction] });
+    expect(p.principal).toEqual({ is: "App::User" });
+    expect(p.unless).toEqual(['principal == App::User::"archivist"']);
+  });
+
+  it("records the member count and the composite name in annotations", () => {
+    const set = DenyByDefaultSet({ policies: [member, member], when: ["context.mfa == false"] });
+
+    expect(props(set.floor).annotations).toEqual({ composite: "DenyByDefaultSet", members: "2" });
+  });
+
+  it("refuses an unguarded forbid", () => {
+    expect(() => DenyByDefaultSet({ policies: [member], when: [] })).toThrow(/at least one condition/);
+  });
+
+  it("serializes floor-then-members as Cedar that parses", () => {
+    const set = DenyByDefaultSet({
+      policies: [member],
+      entityType: "App::Document",
+      when: ['resource.classification == "confidential"'],
+      unless: ["context.mfa == true"],
+    });
+
+    const text = emit({ secretFloor: set.floor, docOwnerRead: set.members[0] });
+
+    expect(text.indexOf("forbid (")).toBeLessThan(text.indexOf("permit ("));
+    expect(text).toContain("unless { context.mfa == true }");
+    expect(checkParsePolicySet({ staticPolicies: text }).type).toBe("success");
+  });
+});

package/src/composites/deny-by-default-set.ts

@@ -0,0 +1,98 @@
+/**
+ * DenyByDefaultSet — a forbid floor under a group of permits.
+ *
+ * Cedar is already default-deny, so a floor is not about the absence of a
+ * permit; it is about the presence of a bad one. A `forbid` beats every
+ * `permit` in the same set unconditionally, which makes a forbid the only
+ * construct that survives a later, wider grant. The pattern teams write by hand
+ * is a guarded forbid at the top of a file and a pile of permits under it, with
+ * nothing tying the two together — delete the forbid and the permits keep
+ * working, wider than anyone intended.
+ *
+ * This composite returns both halves from one call, so the floor cannot be
+ * dropped without dropping the members with it.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { Policy } from "../generated/index";
+import type { EntityTypeName, PolicyRef, PolicyScope } from "../generated/index";
+
+export interface DenyByDefaultSetOpts {
+  /**
+   * The permits the floor sits under. They are returned unchanged — the floor
+   * constrains them at evaluation time, not at construction time.
+   */
+  policies: Declarable[];
+  /**
+   * The entity type the floor covers. Omit to make it apply to every resource,
+   * which is the strongest form and worth stating deliberately.
+   */
+  entityType?: EntityTypeName;
+  /**
+   * Actions the floor forbids. Defaults to every action, i.e. an unconstrained
+   * action position.
+   */
+  actions?: PolicyRef | PolicyRef[];
+  /**
+   * The conditions under which the denial applies. Required: a forbid with no
+   * guard denies everything unconditionally and no permit can lift it, which
+   * is a policy set that authorizes nothing.
+   */
+  when: string[];
+  /** Carve-outs from the denial. The break-glass principal usually lives here. */
+  unless?: string[];
+  /** Narrow the floor's principal. A bare entity type becomes `principal is T`. */
+  principal?: EntityTypeName | PolicyScope;
+  /** Merged over the generated annotations; an explicit `id` wins. */
+  annotations?: Record<string, string>;
+}
+
+export interface DenyByDefaultSetResources {
+  /** The `forbid` policy. Emitted first in declaration order. */
+  floor: Declarable;
+  /** The permits, unchanged and in the order given. */
+  members: Declarable[];
+  /** `[floor, ...members]`, for `export const … = DenyByDefaultSet(…).all`. */
+  all: Declarable[];
+}
+
+function scope(value: EntityTypeName | PolicyScope | undefined): PolicyScope {
+  if (value === undefined) return {};
+  return typeof value === "string" ? { is: value } : value;
+}
+
+function actionScope(actions: DenyByDefaultSetOpts["actions"]): PolicyScope {
+  if (actions === undefined) return {};
+  if (Array.isArray(actions)) {
+    return actions.length === 1 ? { eq: actions[0] } : { in: actions };
+  }
+  return { eq: actions };
+}
+
+/**
+ * A guarded `forbid` plus the permits it governs.
+ */
+export function DenyByDefaultSet(opts: DenyByDefaultSetOpts): DenyByDefaultSetResources {
+  if (opts.when.length === 0) {
+    throw new Error(
+      "DenyByDefaultSet: `when` must carry at least one condition. An unguarded forbid " +
+        "overrides every permit in the set, so the result would authorize nothing.",
+    );
+  }
+
+  const floor = new Policy({
+    effect: "forbid",
+    principal: scope(opts.principal),
+    action: actionScope(opts.actions),
+    resource: scope(opts.entityType),
+    when: opts.when,
+    ...(opts.unless && opts.unless.length > 0 ? { unless: opts.unless } : {}),
+    annotations: {
+      composite: "DenyByDefaultSet",
+      members: String(opts.policies.length),
+      ...(opts.annotations ?? {}),
+    },
+  });
+
+  return { floor, members: [...opts.policies], all: [floor, ...opts.policies] };
+}

package/src/composites/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Cedar lexicon composites.
+ *
+ * Cedar has no functions, no modules, no loops, and templates with exactly two
+ * slots — so every repeated policy shape is copy-paste in `.cedar` text. These
+ * factories are where that repetition goes instead.
+ */
+
+export { OwnerCanManage } from "./owner-can-manage";
+export type { OwnerCanManageOpts } from "./owner-can-manage";
+
+export { DenyByDefaultSet } from "./deny-by-default-set";
+export type { DenyByDefaultSetOpts, DenyByDefaultSetResources } from "./deny-by-default-set";

package/src/composites/owner-can-manage.ts

@@ -0,0 +1,80 @@
+/**
+ * OwnerCanManage — the ownership grant, written once.
+ *
+ * "The owner of a thing may act on it" is the most-repeated shape in every
+ * Cedar policy set, and hand-writing it per entity type is where the two
+ * classic mistakes get made: the `when` guard names an attribute the schema
+ * spells differently, or the grant is written wide and the scoping clause is
+ * forgotten. Cedar itself cannot help — it has no functions, no modules, and
+ * templates carry exactly two slots. A TypeScript factory is the only place
+ * this abstraction can live.
+ *
+ * The composite emits a permit whose resource scope is pinned with `is` and
+ * whose ownership test is a `when` clause, so both halves arrive together or
+ * neither does.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { Policy } from "../generated/index";
+import type { EntityTypeName, PolicyRef, PolicyScope } from "../generated/index";
+
+export interface OwnerCanManageOpts {
+  /** The entity type owners act on, e.g. `"App::Document"`. */
+  entityType: EntityTypeName;
+  /**
+   * Actions the owner is granted. A single action is emitted as `== A`, several
+   * as `in [A, …]`, and none leaves the action position unconstrained — which
+   * is a wide grant, so it has to be asked for by omitting the field.
+   */
+  actions?: PolicyRef | PolicyRef[];
+  /**
+   * The attribute on the resource that holds the owner. Defaults to `owner`,
+   * the name the bundled schema and most Cedar examples use.
+   */
+  ownerAttribute?: string;
+  /**
+   * Narrow the principal beyond "anyone". A bare entity type string becomes
+   * `principal is T`; a full scope is passed through.
+   */
+  principal?: EntityTypeName | PolicyScope;
+  /** Extra `when` clauses, appended after the ownership test. */
+  when?: string[];
+  /** `unless` clauses. An MFA requirement is the usual one. */
+  unless?: string[];
+  /** Merged over the generated annotations; an explicit `id` wins. */
+  annotations?: Record<string, string>;
+}
+
+function actionScope(actions: OwnerCanManageOpts["actions"]): PolicyScope {
+  if (actions === undefined) return {};
+  if (Array.isArray(actions)) {
+    return actions.length === 1 ? { eq: actions[0] } : { in: actions };
+  }
+  return { eq: actions };
+}
+
+function principalScope(principal: OwnerCanManageOpts["principal"]): PolicyScope {
+  if (principal === undefined) return {};
+  return typeof principal === "string" ? { is: principal } : principal;
+}
+
+/**
+ * One permit: the owner of an `entityType` may take `actions` on it.
+ */
+export function OwnerCanManage(opts: OwnerCanManageOpts): Declarable {
+  const ownerAttribute = opts.ownerAttribute ?? "owner";
+
+  return new Policy({
+    effect: "permit",
+    principal: principalScope(opts.principal),
+    action: actionScope(opts.actions),
+    resource: { is: opts.entityType },
+    when: [`resource.${ownerAttribute} == principal`, ...(opts.when ?? [])],
+    ...(opts.unless && opts.unless.length > 0 ? { unless: opts.unless } : {}),
+    annotations: {
+      composite: "OwnerCanManage",
+      scopedTo: opts.entityType,
+      ...(opts.annotations ?? {}),
+    },
+  });
+}