# How to build a policy decision app

Choose this pattern when its answer is the one your app gives. The answer is one XACML 3.0 decision: permit, deny, not-applicable, indeterminate. A policy that applies gives permit or deny. If none applies, the answer is not-applicable. If the request cannot be judged, it is indeterminate.

The standard is OASIS XACML 3.0 policy decision point (https://docs.oasis-open.org/xacml/3.0/xacml-3.0-core-spec-os-en.html). The guide builds the Emporous admission example; put your own rules in its place.

**Figure: The steps, in order.** 4 steps. Each section below is one of them.

| Step | What happens |
| --- | --- |
| 1. Write the prompt | start from Emporous admission |
| 2. Check the prompt | node builder/cli.mjs check |
| 3. Build it and pass the gate | just vv in the locked SDK |
| 4. Publish it | GitHub Pages |

## 1. Write the prompt

Start from the Emporous admission prompt, the policy decision example with the fewest rules (5 rules). Keep pattern set to policyDecision. Replace the fields, answers, rules and examples of its app with your own.

```
{
  "schema": "prism/prompt/1",
  "goal": "Decide if Emporous lets an object into a namespace. Each object must come from someone who is allowed to add it there.",
  "pattern": "policyDecision",
  "repository": "afflom/emporous",
  "app": {
    "name": "emporous-admit-policy",
    "title": "Emporous admission",
    "purpose": "Decide whether one representation is admitted under the scope its namespace names, from the scope, its realization, the principal and the bytes.",
    "fields": [
      {
        "name": "namespace",
        "kind": "choice",
        "values": [
          "scoped",
          "unscoped",
          "conflicted"
        ],
        "means": "whether the namespace names exactly one scope, none, or more than one"
      },
      {
        "name": "realization",
        "kind": "choice",
        "values": [
          "known",
          "unknown"
        ],
        "means": "whether the registry knows the realization the scope names"
      },
      {
        "name": "principal",
        "kind": "choice",
        "values": [
          "authorized",
          "unauthorized"
        ],
        "means": "whether a capability-edge walk reaches the principal from the scope authorization"
      },
      {
        "name": "bytes",
        "kind": "choice",
        "values": [
          "realizable",
          "refused"
        ],
        "means": "whether the realization carries the bytes to a canonical form"
      }
    ],
    "outcomes": [
      "permit",
      "deny",
      "not-applicable",
      "indeterminate"
    ],
    "meanings": {
      "permit": "XACML 3.0 section 7: Permit; the object kappa, the representation kappa and a DerivedFrom edge are written",
      "deny": "XACML 3.0 section 7: Deny; StoreError::Rejected and no DerivedFrom edge is written",
      "not-applicable": "XACML 3.0 section 7: NotApplicable; the namespace names no scope, so no policy governs it",
      "indeterminate": "XACML 3.0 section 7: Indeterminate; the scope cannot be evaluated, because its realization is unknown or the namespace names several scopes"
    },
    "rules": [
      {
        "when": [
          {
            "field": "namespace",
            "op": "is",
            "value": "unscoped"
          }
        ],
        "then": "not-applicable",
        "why": "crates/admission/src/scope.rs scope_of_namespace: the namespace names no scope, StoreError::NotFound"
      },
      {
        "when": [
          {
            "field": "namespace",
            "op": "is",
            "value": "conflicted"
          }
        ],
        "then": "indeterminate",
        "why": "crates/admission/src/scope.rs: a namespace naming more than one scope is StoreError::Conflict"
      },
      {
        "when": [
          {
            "field": "realization",
            "op": "is",
            "value": "unknown"
          }
        ],
        "then": "indeterminate",
        "why": "crates/admission/src/admit.rs: the registry does not know the realization, StoreError::NotFound (EA-03)"
      },
      {
        "when": [
          {
            "field": "principal",
            "op": "is",
            "value": "unauthorized"
          }
        ],
        "then": "deny",
        "why": "crates/admission/src/admit.rs and auth.rs: the principal is not authorized by the scope capability, StoreError::Rejected (EA-05)"
      },
      {
        "when": [
          {
            "field": "bytes",
            "op": "is",
            "value": "refused"
          }
        ],
        "then": "deny",
        "why": "crates/admission/src/realize.rs: the realization refuses the bytes, StoreError::Rejected"
      }
    ],
    "otherwise": "permit",
    "otherwiseWhy": "SPEC.md 5.1: the canonical form is ingested on the scope axis and the received bytes at their own kappa, joined by a DerivedFrom edge",
    "properties": [
      {
        "kind": "never",
        "when": [
          {
            "field": "principal",
            "op": "is",
            "value": "unauthorized"
          }
        ],
        "then": "permit",
        "why": "EA-05: admission into a namespace requires the capability its scope names"
      },
      {
        "kind": "never",
        "when": [
          {
            "field": "realization",
            "op": "is",
            "value": "unknown"
          }
        ],
        "then": "permit",
        "why": "EA-03: a scope naming a realization the registry does not know is reported as not found"
      },
      {
        "kind": "always",
        "when": [
          {
            "field": "namespace",
            "op": "is",
            "value": "scoped"
          },
          {
            "field": "realization",
            "op": "is",
            "value": "known"
          },
          {
            "field": "principal",
            "op": "is",
            "value": "unauthorized"
          }
        ],
        "then": "deny",
        "why": "admit.rs checks authorization before the realization reads the bytes"
      },
      {
        "kind": "always",
        "when": [
          {
            "field": "namespace",
            "op": "is",
            "value": "unscoped"
          }
        ],
        "then": "not-applicable",
        "why": "without a scope there is no realization, axis or authorization to apply"
      }
    ],
    "examples": [
      {
        "request": "scoped known authorized realizable",
        "response": "permit"
      },
      {
        "request": "scoped known unauthorized realizable",
        "response": "deny"
      },
      {
        "request": "scoped unknown authorized realizable",
        "response": "indeterminate"
      },
      {
        "request": "unscoped known authorized realizable",
        "response": "not-applicable"
      },
      {
        "request": "scoped known authorized refused",
        "response": "deny"
      },
      {
        "request": "conflicted known authorized realizable",
        "response": "indeterminate"
      },
      {
        "request": "scoped known unauthorized refused",
        "response": "deny"
      }
    ]
  },
  "stakeholders": [
    {
      "name": "Publisher",
      "text": "Admits artefact representations into a namespace and needs each admission addressed by the canonical form its scope selects.",
      "concerns": [
        "Correct answers"
      ]
    },
    {
      "name": "Supply-chain auditor",
      "text": "Assesses blast radius over ComposedOf and needs every object in a namespace admitted by a principal its capability authorizes.",
      "concerns": [
        "Proved guarantees",
        "Authorized admission"
      ]
    }
  ],
  "concerns": [
    {
      "name": "Authorized admission",
      "text": "No object kappa and no DerivedFrom edge exist for a principal the scope capability does not reach.",
      "model": "security"
    }
  ],
  "components": [
    {
      "name": "kappa-registry",
      "kind": "externalSystem",
      "text": "The pinned upstream registry Emporous imports, whose KappaStore ingests content and resolves edges."
    },
    {
      "name": "KappaStore",
      "kind": "database",
      "text": "The content-addressed store holding objects, representations, scopes and capability edges."
    }
  ],
  "threats": [
    {
      "name": "Unauthorized admission",
      "text": "A principal outside the scope capability admits an object into the namespace.",
      "stride": "elevationOfPrivilege",
      "asset": "request",
      "likelihood": "medium",
      "impact": "critical",
      "control": {
        "name": "Capability-edge walk",
        "text": "Admission is denied unless the walk from the scope authorization reaches the principal.",
        "evidence": [
          {
            "kind": "proof",
            "reference": "EmporousAdmitPolicyProofs::inv001Holds"
          },
          {
            "kind": "gate",
            "reference": "EA-05 features/suites/admission.feature"
          }
        ]
      }
    },
    {
      "name": "Realization chosen in code",
      "text": "The admission path names a realization or axis literal instead of reading it from the scope.",
      "stride": "tampering",
      "asset": "source",
      "likelihood": "low",
      "impact": "major",
      "control": {
        "name": "Read from the scope",
        "text": "The realization and axis are read from the scope and a literal on the admission path fails the gate.",
        "evidence": [
          {
            "kind": "gate",
            "reference": "EA-03 features/suites/admission.feature"
          },
          {
            "kind": "gate",
            "reference": "cargo xtask audit-parametric"
          }
        ]
      }
    },
    {
      "name": "Unknown realization admitted",
      "text": "A scope names a realization the registry does not know and the bytes are admitted unrealized.",
      "stride": "tampering",
      "asset": "answer",
      "likelihood": "low",
      "impact": "major",
      "control": {
        "name": "Not found, not admitted",
        "text": "An unknown realization is indeterminate and never permitted.",
        "evidence": [
          {
            "kind": "proof",
            "reference": "EmporousAdmitPolicyProofs::inv002Holds"
          }
        ]
      }
    }
  ],
  "quality": [
    {
      "characteristic": "Security",
      "subcharacteristic": "Resistance",
      "requirement": "No unauthorized admission",
      "text": "No request from an unauthorized principal is permitted.",
      "measure": "Unauthorized permits",
      "measureText": "Requests with an unauthorized principal that answer permit.",
      "threshold": 0
    },
    {
      "characteristic": "Functional suitability",
      "subcharacteristic": "Functional completeness",
      "requirement": "Every admission condition decided",
      "text": "Each admission condition of SPEC.md 6.3 and the namespace conflict has its own answer.",
      "measure": "Undecided conditions",
      "measureText": "Admission failure conditions no rule decides.",
      "threshold": 0
    }
  ],
  "journeys": [
    {
      "stakeholder": "Publisher",
      "steps": [
        "REQ-001",
        "REQ-003",
        "REQ-005",
        "otherwise"
      ]
    },
    {
      "stakeholder": "Supply-chain auditor",
      "steps": [
        "REQ-002",
        "REQ-004",
        "INV-001",
        "INV-003"
      ]
    }
  ]
}
```

The prompt as raw JSON: ../../examples/prompts/emporous-admit-policy.prompt.json

It sets these members. Each meaning is quoted from the input schema of prism\_prompt.

| Member | Presence | In this prompt | Meaning |
| --- | --- | --- | --- |
| goal | optional | text | The goal the app is built toward, in one sentence a developer would say. It becomes the spec purpose when app.purpose is left out. |
| pattern | optional | policyDecision | The pattern the behavior follows: decisionTable (OMG DMN 1.5, hit policy FIRST, the default), policyDecision (OASIS XACML 3.0: the answers are exactly permit, deny, not-applicable and indeterminate) or stateMachine (OMG UML 2.5.1: the answer is the next state, and machine is required). |
| repository | optional | afflom/emporous | owner/name of the repository the app will live in, for its page and links. |
| app | required | name, title, purpose, fields, outcomes, meanings, rules, otherwise, otherwiseWhy, properties, examples | The whole app as a prism/spec/1 spec, the input of prism-code's prism\_spec. Its members are below. |
| app.name | optional | emporous-admit-policy | Lower case and hyphens, such as loan-approval. |
| app.title | optional | Emporous admission |  |
| app.purpose | required | text | What the app decides, in one sentence. |
| app.fields | required | 4 entries | One request is these values in order, separated by spaces. |
| app.outcomes | required | 4 entries | Lower-case words; invalid is reserved. |
| app.meanings | optional | permit, deny, not-applicable, indeterminate | What each answer means, such as {"review": "a person must decide"}. |
| app.rules | required | 5 entries | In order; the first that matches decides. |
| app.otherwise | required | permit | The answer when no rule matches. |
| app.otherwiseWhy | optional | text | Why, in a few words, such as "it enforces INV-001". |
| app.properties | optional | 4 entries | What must never or always happen; each becomes a theorem Lean proves. |
| app.examples | optional | 7 entries | Requests and their expected answers; each becomes an acceptance vector. |
| stakeholders | optional | 2 entries | Who the app is for. A Verifier, anyone who replays the holo before trusting it, is always added. |
| concerns | optional | 1 entry | What the stakeholders care about, each viewed in one model. |
| components | optional | 2 entries | Systems outside the app that send it requests or read its answers. |
| threats | optional | 3 entries | What can go wrong, beyond the threats every app has (an oversized or malformed request, a substituted holo or source, a granted capability, an answer a property rules out). |
| quality | optional | 2 entries | How good is good enough, as ISO/IEC 25010:2023 requirements with a measure and its threshold. |
| journeys | optional | 2 entries | Ordered steps a stakeholder takes. A step is a rule ID (REQ-001), a property ID (INV-001), otherwise or refuse. |

## 2. Check the prompt

In a clone of prism-devrel, run the check on your prompt. It checks the prompt and prints what the app will claim, writing nothing.

```
git clone https://github.com/afflom/prism-devrel.git && cd prism-devrel
node builder/cli.mjs check examples/emporous-admit-policy.prompt.json
```

For the Emporous admission prompt it prints this.

```
Emporous admission: Policy decision (OASIS XACML 3.0 policy decision point), 82 files, 35 acceptance vectors
EA-01: The app never answers permit when principal is unauthorized
EA-02: The app never answers permit when realization is unknown
EA-03: The app always answers deny when namespace is scoped and realization is known and principal is unauthorized
EA-04: The app always answers not-applicable when namespace is unscoped
EA-05: The architecture description declares every stakeholder, concern, component, edge, viewpoint and view it references
EA-06: The ISO/IEC 25010 quality model numbers every characteristic, subcharacteristic, requirement and measure, and every parent it names is declared
EA-07: Every compliance obligation is numbered in order and names its evidence
```

Exit codes: 0 done, 2 the prompt was refused (the reason is printed), 64 usage.

## 3. Build it and pass the gate

Save this script as verify.sh in the clone, with PROMPT set to your prompt. It is the pages workflow's own steps for an example.

```
set -euo pipefail
PROMPT=examples/emporous-admit-policy.prompt.json
RUNNER_TEMP=$(mktemp -d)
field() { node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync("frame.lock", "utf8")).source[process.argv[1]])' "$1"; }
instance="$RUNNER_TEMP/instance"
git init -q "$instance"
git -C "$instance" fetch -q --depth 1 "https://github.com/$(field repository)" "$(field commit)"
git -C "$instance" checkout -q --detach FETCH_HEAD
test "$(git -C "$instance" rev-parse HEAD)" = "$(field commit)"
node builder/cli.mjs build "$PROMPT" --out "$instance"
image=$(sed -n 's/.*"sdk_image":"\([^"]*\)".*/\1/p' prismpm.lock)
if [[ ! $image =~ ^[a-z0-9.-]+(:[0-9]{1,5})?/[a-z0-9./_-]+@sha256:[0-9a-f]{64}$ ]]; then
  printf '%s\n' 'prismpm.lock does not select an immutable SDK image' >&2
  exit 64
fi
docker_config=$(mktemp -d)
# The SDK's /tmp is a private directory on the runner's own disk, so the
# build's scratch space is bounded by the disk the runner has, not by a
# fixed size; it is removed with the credentials when the step ends.
scratch=$(mktemp -d)
mkdir -p "$scratch/prismpm-home/.docker"
trap 'rm -rf "$docker_config" "$scratch"' EXIT
printf '{}\n' >"$docker_config/config.json"
docker run --rm \
  --user "$(id -u):$(id -g)" \
  --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  --volume "$scratch:/tmp" \
  --volume "$instance:$instance" \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume "$docker_config:/tmp/prismpm-home/.docker:ro" \
  --workdir "$instance" \
  --env DOCKER_CONFIG=/tmp/prismpm-home/.docker \
  --env BUILDX_CONFIG=/tmp/prismpm-buildx \
  --env HOME=/tmp/prismpm-home \
  --env PRISMPM_EPHEMERAL_HOME=1 \
  "$image" just vv
```

It calls git, node and docker. Run it, and keep the log.

```
bash verify.sh 2>&1 | tee verify.log
```

When it passes, the verified holo is in the instance the script made under RUNNER\_TEMP, at "$instance"/app/.prism/build/\*/\*.holo.

## 4. Publish it

- [How to publish an app on GitHub Pages](../../guides/publish/index.md): its own repository proves and serves it.

## What the gate proves

The Policy decision obligation of OASIS XACML 3.0 policy decision point names its evidence: EmporousAdmitPolicy::judge, EmporousAdmitPolicy::encodeAnswer.

Each property of the Emporous admission prompt is a theorem the Lean kernel checks for every request.

| Property | Statement | Theorem |
| --- | --- | --- |
| INV-001 | It never answers permit when principal is unauthorized. | EmporousAdmitPolicyProofs::inv001Holds |
| INV-002 | It never answers permit when realization is unknown. | EmporousAdmitPolicyProofs::inv002Holds |
| INV-003 | It always answers deny when namespace is scoped and realization is known and principal is unauthorized. | EmporousAdmitPolicyProofs::inv003Holds |
| INV-004 | It always answers not-applicable when namespace is unscoped. | EmporousAdmitPolicyProofs::inv004Holds |

## Every policy decision example

- [Open policy](../../examples/holo-open-policy/index.md). Decide if Holo Search opens the app an address names. Nothing runs unless its bytes match the address, its model checks and its tests pass.
- [Namespace authorization](../../examples/kappa-namespace-authorization/index.md). Decide if kappa-registry lets someone change a namespace. Only its owner, a key holder or a short chain of trust can write.
- [Axiom policy](../../examples/lexlean-axiom-policy/index.md). Decide if a declaration uses only the axioms its source allows. Then lexlean verify publishes nothing that rests on more.
- [GNAF claim wording](../../examples/gnaf-claim-wording/index.md). Decide which words a GNAF document may use for a claim. No README or ledger may say more than the Lean kernel checked.
- [Emporous admission](../../examples/emporous-admit-policy/index.md). Decide if Emporous lets an object into a namespace. Each object must come from someone who is allowed to add it there.
- [Portal publication](../../examples/foundry-web-publication/index.md). Decide if foundry-web may publish a portal release. Only the exact build that was checked and approved can go live.

## Other patterns

- [How to build a decision table app](../../guides/decision-table/index.md): The rules are tried in order, and the first one that matches gives the answer.
- [How to build a state machine app](../../guides/state-machine/index.md): The answer is the next state, given the current state and an event.
