@intentius/chant-lexicon-cedar 0.44.8

package/dist/types/index.d.ts

@@ -0,0 +1,219 @@
+// Code generated by chant generate. DO NOT EDIT.
+import type { Declarable } from "@intentius/chant/declarable";
+
+/**
+ * Entity UID of `App::Application`.
+ */
+export type ApplicationUid = `App::Application::"${string}"`;
+
+export interface ApplicationAttributesProps {
+  name: string;
+  owner: TeamUid;
+}
+
+/**
+ * Entity UID of `App::Document`.
+ * Member of: App::Folder.
+ */
+export type DocumentUid = `App::Document::"${string}"`;
+
+export interface DocumentAttributesProps {
+  classification: string;
+  folder: FolderUid;
+  owner: UserUid;
+  public: boolean;
+  tags: string[];
+  title: string;
+}
+
+/**
+ * Entity UID of `App::Folder`.
+ */
+export type FolderUid = `App::Folder::"${string}"`;
+
+export interface FolderAttributesProps {
+  name: string;
+  owner: UserUid;
+  tags: string[];
+}
+
+/**
+ * Entity UID of `App::Group`.
+ */
+export type GroupUid = `App::Group::"${string}"`;
+
+export interface GroupAttributesProps {
+  description?: string;
+  name: string;
+}
+
+/**
+ * Entity UID of `App::ServiceAccount`.
+ * Member of: App::Group.
+ */
+export type ServiceAccountUid = `App::ServiceAccount::"${string}"`;
+
+export interface ServiceAccountAttributesProps {
+  name: string;
+  owner: UserUid;
+  rotatedAt?: string;
+}
+
+/**
+ * Entity UID of `App::Team`.
+ * Member of: App::Group.
+ */
+export type TeamUid = `App::Team::"${string}"`;
+
+export interface TeamAttributesProps {
+  costCenter?: string;
+  name: string;
+}
+
+/**
+ * Entity UID of `App::User`.
+ * Member of: App::Group, App::Team.
+ */
+export type UserUid = `App::User::"${string}"`;
+
+export interface UserAttributesProps {
+  department: string;
+  email: string;
+  level: number;
+  manager?: UserUid;
+  mfaEnabled: boolean;
+  roles: string[];
+}
+
+export interface AdminContextProps {
+  breakGlass?: boolean;
+  mfa: boolean;
+}
+
+export interface ApproveContextProps {
+  mfa: boolean;
+}
+
+export interface CommentContextProps {
+  mfa: boolean;
+  reason?: string;
+}
+
+export interface CreateContextProps {
+  mfa: boolean;
+  reason?: string;
+}
+
+export interface DeleteContextProps {
+  approvedBy?: UserUid;
+  mfa: boolean;
+}
+
+export interface ListContextProps {
+  mfa: boolean;
+  sourceIp?: string;
+}
+
+export interface ReadContextProps {
+  mfa: boolean;
+  sourceIp?: string;
+}
+
+export interface ShareContextProps {
+  approvedBy?: UserUid;
+  mfa: boolean;
+}
+
+export interface WriteContextProps {
+  mfa: boolean;
+  reason?: string;
+}
+
+/** Every entity type name the schema declares, as Cedar writes it. */
+export type EntityTypeName = "App::Application" | "App::Document" | "App::Folder" | "App::Group" | "App::ServiceAccount" | "App::Team" | "App::User";
+
+/** Every entity UID the schema can produce. */
+export type EntityUid = ApplicationUid | DocumentUid | FolderUid | GroupUid | ServiceAccountUid | TeamUid | UserUid;
+
+/** Every action UID the schema declares. */
+export type ActionUid = "App::Action::\"admin\"" | "App::Action::\"approve\"" | "App::Action::\"comment\"" | "App::Action::\"create\"" | "App::Action::\"delete\"" | "App::Action::\"list\"" | "App::Action::\"read\"" | "App::Action::\"share\"" | "App::Action::\"write\"";
+
+/** Anything a policy scope may name. */
+export type PolicyRef = EntityUid | ActionUid;
+
+/** A Cedar policy either permits or forbids; there is no third effect. */
+export type PolicyEffect = "permit" | "forbid";
+
+/**
+ * One scope position (`principal`, `action`, `resource`).
+ * 
+ * `{}` is the unconstrained form Cedar writes as a bare variable. The
+ * constrained forms mirror the grammar: `== E`, `in E`, `in [E, …]`,
+ * `is T`, and `is T in E`.
+ */
+export type PolicyScope =
+  | Record<string, never>
+  | { eq: PolicyRef; in?: never; is?: never }
+  | { in: PolicyRef | PolicyRef[]; eq?: never; is?: never }
+  | { is: EntityTypeName; in?: PolicyRef | PolicyRef[]; eq?: never };
+
+/**
+ * The props of a `Cedar::Policy`.
+ * 
+ * `when`/`unless` carry Cedar expression text. They stay strings because
+ * Cedar's expression grammar is the policy language itself — typing it in
+ * TypeScript is import/reconcile's problem (epic #1645 sub-issue 6), not
+ * codegen's.
+ */
+export interface PolicyProps {
+  /** Defaults to `permit` when omitted. */
+  effect?: PolicyEffect;
+  principal?: PolicyScope;
+  action?: PolicyScope;
+  resource?: PolicyScope;
+  /** Cedar expression strings, each emitted as its own `when { … }` clause. */
+  when?: string[];
+  /** Cedar expression strings, each emitted as its own `unless { … }` clause. */
+  unless?: string[];
+  /** Emitted as `@key("value")`; an explicit `id` wins over the logical name. */
+  annotations?: Record<string, string>;
+}
+
+export declare const Policy: new (props: PolicyProps) => Declarable;
+
+export declare const Application: new (props: ApplicationAttributesProps) => Declarable;
+export declare const ApplicationAttributes: new (props: ApplicationAttributesProps) => Declarable;
+export declare const Document: new (props: DocumentAttributesProps) => Declarable;
+export declare const DocumentAttributes: new (props: DocumentAttributesProps) => Declarable;
+export declare const Folder: new (props: FolderAttributesProps) => Declarable;
+export declare const FolderAttributes: new (props: FolderAttributesProps) => Declarable;
+export declare const Group: new (props: GroupAttributesProps) => Declarable;
+export declare const GroupAttributes: new (props: GroupAttributesProps) => Declarable;
+export declare const ServiceAccount: new (props: ServiceAccountAttributesProps) => Declarable;
+export declare const ServiceAccountAttributes: new (props: ServiceAccountAttributesProps) => Declarable;
+export declare const Team: new (props: TeamAttributesProps) => Declarable;
+export declare const TeamAttributes: new (props: TeamAttributesProps) => Declarable;
+export declare const User: new (props: UserAttributesProps) => Declarable;
+export declare const UserAttributes: new (props: UserAttributesProps) => Declarable;
+
+export declare const AdminAction: "App::Action::\"admin\"";
+export declare const AdminContext: new (props: AdminContextProps) => Declarable;
+export declare const ApproveAction: "App::Action::\"approve\"";
+export declare const ApproveContext: new (props: ApproveContextProps) => Declarable;
+export declare const CommentAction: "App::Action::\"comment\"";
+export declare const CommentContext: new (props: CommentContextProps) => Declarable;
+export declare const CreateAction: "App::Action::\"create\"";
+export declare const CreateContext: new (props: CreateContextProps) => Declarable;
+export declare const DeleteAction: "App::Action::\"delete\"";
+export declare const DeleteContext: new (props: DeleteContextProps) => Declarable;
+export declare const ListAction: "App::Action::\"list\"";
+export declare const ListContext: new (props: ListContextProps) => Declarable;
+export declare const ReadAction: "App::Action::\"read\"";
+export declare const ReadContext: new (props: ReadContextProps) => Declarable;
+export declare const ShareAction: "App::Action::\"share\"";
+export declare const ShareContext: new (props: ShareContextProps) => Declarable;
+export declare const WriteAction: "App::Action::\"write\"";
+export declare const WriteContext: new (props: WriteContextProps) => Declarable;
+
+export declare const ALL_ACTIONS: readonly ActionUid[];
+export declare const ALL_ENTITY_TYPES: readonly EntityTypeName[];

package/dist/validate-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env tsx
+export {};
+//# sourceMappingURL=validate-cli.d.ts.map

package/dist/validate-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-cli.d.ts","sourceRoot":"","sources":["../src/validate-cli.ts"],"names":[],"mappings":""}

package/dist/validate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Validate the generated lexicon-cedar artifacts.
+ *
+ * The required-name list below is the surface this package publishes when it
+ * generates from its own bundled default schema, which is what `prepack`,
+ * `just check-lexicons` and CI all do. It is not a claim about a user's
+ * project schema — theirs produces their own names, and `coverage()` is the
+ * check that answers whether their schema is fully reachable.
+ *
+ * Listing them explicitly is the point: `src/generated/` is gitignored, so
+ * without this list nothing in the repository records what the default schema
+ * is supposed to produce, and a codegen change that quietly dropped every
+ * action would still pass "the registry parses".
+ */
+import { type ValidateResult } from "@intentius/chant/codegen/validate";
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+/** Exposed so tests can assert the list stays above the tier-3 bar. */
+export declare const requiredNames: readonly string[];
+/**
+ * Validate the generated lexicon-cedar artifacts.
+ */
+export declare function validate(opts?: {
+    basePath?: string;
+}): Promise<ValidateResult>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAElG,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAmDvF,uEAAuE;AACvE,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAmB,CAAC;AAE/D;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAQpF"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@intentius/chant-lexicon-cedar",
+  "version": "0.44.8",
+  "description": "Cedar lexicon for chant — typed authoring for Cedar authorization policies",
+  "license": "Apache-2.0",
+  "homepage": "https://intentius.io/chant",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/INTENTIUS/chant.git",
+    "directory": "lexicons/cedar"
+  },
+  "bugs": {
+    "url": "https://github.com/INTENTIUS/chant/issues"
+  },
+  "keywords": [
+    "infrastructure-as-code",
+    "iac",
+    "typescript",
+    "cedar",
+    "authorization",
+    "policy",
+    "chant"
+  ],
+  "type": "module",
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": {
+      "development": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./src/*.ts"
+    },
+    "./lint/post-synth": {
+      "development": "./src/lint/post-synth/index.ts",
+      "types": "./dist/lint/post-synth/index.d.ts",
+      "default": "./src/lint/post-synth/index.ts"
+    },
+    "./manifest": "./dist/manifest.json",
+    "./meta": "./dist/meta.json",
+    "./types": "./dist/types/index.d.ts"
+  },
+  "scripts": {
+    "generate": "tsx src/codegen/generate-cli.ts",
+    "bundle": "tsx src/package-cli.ts",
+    "validate": "tsx src/validate-cli.ts",
+    "docs": "tsx src/codegen/docs-cli.ts",
+    "docs:dev": "cd docs && npm run dev",
+    "docs:build": "cd docs && npm install && npm run build",
+    "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete"
+  },
+  "dependencies": {
+    "@cedar-policy/cedar-wasm": "4.12.0"
+  },
+  "devDependencies": {
+    "@intentius/chant": "*",
+    "tsc-alias": "^1.8.17",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "zod": "^4.3.6",
+    "@intentius/chant": "^0.44.8",
+    "typescript": "^5.9.3"
+  }
+}

package/src/avp/OWNERSHIP.md

@@ -0,0 +1,125 @@
+# Ownership channel: Amazon Verified Permissions
+
+The design record for chant #1652, epic #1645. The epic left this open ("store-scoped
+until proven finer") because the tier-2 check in `chant dev check-lexicon` exists
+precisely to stop a lexicon declaring a channel it cannot read.
+
+The full cedar docs site is #1654's. This file is the decision, kept beside the code
+that implements it so the two cannot drift.
+
+## The constraint
+
+AVP is the only target chant deploys to where the resource that needs an ownership
+marker cannot carry one.
+
+- A **policy store** is taggable. `TagResource` / `ListTagsForResource` take the same
+  key/value map every other AWS resource has.
+- An **individual policy** is not. `CreatePolicy` accepts a policy store id, a
+  definition, and a client token. There is no tag surface on it, and no
+  `TagResource` call that accepts a policy ARN, because a policy has no ARN.
+
+That matters because a store is not the unit of ownership. One store holds the
+policies from a chant build *and* whatever anyone added in the console, and the whole
+reason ownership exists is to let `delete` be precise: an undeclared policy carrying
+chant's marker is a safe delete candidate, an undeclared policy without one is
+somebody else's grant and must never be touched. A store-level answer cannot make that
+distinction for anything inside the store.
+
+## The decision
+
+**Two channels, one set of keys, and only the per-policy one resolves a verdict about
+a policy.**
+
+| Channel | Target | Read via | What it answers |
+|---|---|---|---|
+| Description marker | one policy | `ListPolicies` / `GetPolicy` → `definition.static.description` | is *this policy* chant's |
+| Tags | the store | `ListTagsForResource` on the store ARN | is *this store* chant's |
+
+Both use `AVP_OWNERSHIP_KEYS` — `chant:managed-by`, `chant:stack`, `chant:env` — the
+same names the aws lexicon stamps into tags. `ownershipChannel` declares one
+`ChannelKeys`, and a lexicon whose two channels disagreed on key names would be two
+conventions wearing one declaration.
+
+### The encoding
+
+`Definition.Static.Description` is a free-form string, so the marker rides in a
+trailing bracketed segment and the author's own text is preserved ahead of it:
+
+```
+Owners always read their own documents. [chant:managed-by=chant chant:stack=authz chant:env=prod chant:policy-id=owner-read]
+```
+
+- Values are **percent-encoded**, so a stack named `my stack` or an id containing `]`
+  round-trips instead of corrupting the segment.
+- `chant:policy-id` is recorded beside the marker but is deliberately **not** part of
+  `AVP_OWNERSHIP_KEYS`. It is not an ownership claim — `hasOwnershipMarker` must not
+  consult it — it is there because `ListPolicies` returns descriptions and not
+  statements, so without it every live policy costs a second `GetPolicy` round trip
+  just to learn which chant entity it belongs to.
+- AVP caps the description at **150 characters**. When the author's text plus the
+  marker exceed it, the *text* is truncated and the marker is kept whole. The failure
+  direction matters: a dropped marker turns an owned policy into a foreign one, a
+  foreign policy is never deleted, and the estate would accumulate undeletable
+  policies with nothing reported anywhere.
+
+### Declared read paths
+
+```ts
+ownershipChannel: {
+  keys: AVP_OWNERSHIP_KEYS,
+  reads: ["describeResources", "exportResources"],
+}
+```
+
+Both are implemented and both genuinely read the description:
+
+- `describeResources` gets it from the `ListPolicies` enumeration it already runs, so
+  the verdict costs nothing extra. Every returned resource carries `owned` or
+  `foreign`; with `owned: true`, a policy without the marker becomes NOT-OBSERVED with
+  reason `filtered` rather than disappearing (it exists — it just isn't chant's, and a
+  declared resource that exists must not classify as `create`).
+- `exportResources` reads the same field to implement its `owned` filter.
+
+`observeResourcesDeep` is **not** declared, because this lexicon does not implement it.
+That is the whole point of the per-path declaration (chant #1348): a caller learns
+before asking whether `owned: true` is answerable on the path it is about to use.
+
+### Where the verdict is `unknown`
+
+Ownership verdicts are total, so every path that cannot read the marker says `unknown`
+rather than degrading silently. In practice this reader never returns a resource whose
+description it did not read — if the enumeration failed, the entity is NOT-OBSERVED,
+not present-with-an-unknown-verdict — so `unknown` shows up only where core stamps it
+for a lexicon that reported nothing. The obligation is still real for anyone extending
+this file: a new read path that cannot see the description must not be added to
+`reads`.
+
+## Alternatives rejected
+
+**Store-level tags as the only channel.** The epic's provisional position. Rejected
+because it answers a question nobody asks: `lifecycle plan` needs to know whether
+*this policy* is deletable, and "the store is chant's" says nothing about the console
+edit sitting inside it. Kept as the coarse channel (`ownershipFromStoreTags`) because
+it is real information about the store, and free.
+
+**A Cedar annotation, `@chant_managed("chant")`, inside the policy text.** Attractive:
+it is in the artifact, it survives any transport, and it needs no second field. Rejected
+because it changes the walk-away artifact. The epic's test is that an emitted policy
+set is consumed by any Cedar evaluator with chant nowhere in sight, and an annotation
+chant invented is chant in sight — it would show up in every export, every `.cedar`
+file, and every console view of the policy. The description is metadata *about* the
+policy in AVP's own model; the statement is the product.
+
+**A separate policy-store-scoped index (a marker policy, or an S3 object).** That is a
+state file with extra steps, and the lifecycle model exists specifically so ownership
+lives on the resource rather than in something chant has to host and lock.
+
+## Cost, stated plainly
+
+The description is user-writable. Someone can edit it in the console and a chant-owned
+policy becomes `foreign`, which means chant stops offering to delete it — noticeable,
+and safe. The reverse is also possible: pasting chant's marker onto a foreign policy
+makes chant willing to delete it. Tags have exactly the same property, so this is the
+ordinary AWS trust model rather than a new weakness, but the description is more likely
+to be edited by hand than a tag is. Worth knowing before turning on `--owned`
+reconciliation against a shared store.

package/src/avp/ambient.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+import { CEDAR_POLICY_TYPE } from "../serializer";
+import { AVP_AMBIENT_KINDS, observeAvpAmbient } from "./ambient";
+import {
+  markedDescription,
+  mockAvpTransport,
+  statementFor,
+  MOCK_ENV,
+  type MockStore,
+} from "./testdata/mock-transport";
+
+const STORE = "PS-abc123";
+
+/** One declared-and-observed policy, plus two nobody declared. */
+const store: MockStore = {
+  policyStoreId: STORE,
+  policies: [
+    { policyId: "p-1", statement: statementFor("owner-read"), description: markedDescription("owner-read") },
+    {
+      policyId: "p-99",
+      statement: '@id("console-grant")\npermit (\n  principal,\n  action,\n  resource\n);',
+      description: "temporary, added during the incident",
+    },
+    {
+      policyId: "p-100",
+      statement: 'forbid (\n  principal,\n  action,\n  resource is App::Document\n)\nwhen { resource.classification == "secret" };',
+    },
+  ],
+};
+
+const observed: Record<string, ResourceMetadata> = {
+  ownerRead: { type: CEDAR_POLICY_TYPE, status: "STATIC", physicalId: "p-1", ownership: "owned" },
+};
+
+function run(options: Partial<Parameters<typeof observeAvpAmbient>[0]> = {}) {
+  const { http } = mockAvpTransport(store);
+  return observeAvpAmbient({
+    environment: "prod",
+    kinds: [CEDAR_POLICY_TYPE],
+    observed,
+    policyStoreId: STORE,
+    client: { http },
+    env: MOCK_ENV,
+    ...options,
+  });
+}
+
+describe("ambientKinds", () => {
+  it("names the one kind cedar deploys", () => {
+    expect([...AVP_AMBIENT_KINDS]).toEqual([CEDAR_POLICY_TYPE]);
+  });
+});
+
+describe("observeAvpAmbient", () => {
+  it("finds the policies nothing declares and excludes the one that is managed", async () => {
+    const ambient = await run();
+    expect(Object.keys(ambient).sort()).toEqual(["policy/p-100", "policy/p-99"]);
+    expect(ambient["policy/p-99"].ambient).toBe(true);
+    expect(ambient["policy/p-99"].type).toBe(CEDAR_POLICY_TYPE);
+  });
+
+  it("carries the statement and its effect, and stops short of a verdict", async () => {
+    const ambient = await run();
+
+    // The standing grant: a bare permit nobody declared.
+    expect(ambient["policy/p-99"].attributes?.effect).toBe("permit");
+    expect(ambient["policy/p-99"].attributes?.statement).toContain("permit");
+    expect(ambient["policy/p-100"].attributes?.effect).toBe("forbid");
+
+    // Nothing in the metadata calls it dangerous — that is the consumer's call.
+    expect(Object.keys(ambient["policy/p-99"])).not.toContain("standingGrant");
+  });
+
+  it("reports the ownership verdict it can read from the description", async () => {
+    const ambient = await run();
+    expect(ambient["policy/p-99"].ownership).toBe("foreign");
+  });
+
+  it("does not call a declared-but-unobserved policy ambient", async () => {
+    // ownerRead's read failed, so it has no physicalId in `observed` — the
+    // declared-id exclusion is what stops a hole becoming a security finding.
+    const ambient = await run({ observed: {}, declaredPolicyIds: ["owner-read"] });
+    expect(Object.keys(ambient).sort()).toEqual(["policy/p-100", "policy/p-99"]);
+  });
+
+  it("returns nothing when the project declares no policies", async () => {
+    expect(await run({ kinds: ["App::User"] })).toEqual({});
+  });
+
+  it("degrades to empty rather than sinking a managed observation that succeeded", async () => {
+    const broken = await run({
+      client: { http: mockAvpTransport({ ...store, listFails: { code: "ThrottlingException", message: "Rate exceeded", status: 429 } }).http },
+    });
+    expect(broken).toEqual({});
+  });
+
+  it("returns nothing when nothing binds the environment to a store", async () => {
+    const { http } = mockAvpTransport(store);
+    const ambient = await observeAvpAmbient({
+      environment: "prod",
+      kinds: [CEDAR_POLICY_TYPE],
+      observed,
+      client: { http },
+      env: MOCK_ENV,
+    });
+    expect(ambient).toEqual({});
+  });
+
+  it("returns nothing when there are no credentials", async () => {
+    expect(await run({ env: {} })).toEqual({});
+  });
+});