UIAP Policy Extension

UIAP Policy Extension v0.1

Feld	Wert
Status	Draft
Version	0.1
Datum	2026-03-27
Abhängigkeiten	[UIAP-CORE]
Editoren	Patrick

1. Zweck

UIAP Policy Extension v0.1 definiert, wie eine Anwendung Regeln für:

erlaubte Agent-Aktionen,
Bestätigungen,
sensible Daten,
Redaktion,
Audit,
Human Handoff

maschinenlesbar beschreibt und zur Laufzeit auswertet.

Die Extension baut auf UIAP Core v0.1, Capability Model v0.1, Web Profile v0.1 und Action Runtime v0.1 auf.

Normative Begriffe

Die Schlüsselwörter MUSS, DARF NICHT, SOLLTE, KANN in diesem Dokument sind normativ gemäss RFC 2119 und BCP 14 zu interpretieren, wenn und nur wenn sie in GROSSBUCHSTABEN erscheinen.

2. Kennung und Aushandlung

type ExtensionId = "uicp.policy";
type ExtensionVersion = "0.1";

Eine Implementierung, die diese Erweiterung nutzt, MUSS sie im Handshake aushandeln:

{
  "id": "uicp.policy",
  "versions": ["0.1"],
  "required": false
}

3. Geltung und Grundsätze

Policy ist lokal durchsetzbar. Eine App oder Bridge MUSS eine Policy-Entscheidung auch dann durchsetzen können, wenn der Agent etwas anderes will.
Policy ist entscheidungsorientiert, nicht promptorientiert.
Policy trennt Berechtigung, Risiko, Sensitivität, Audit-Pflicht und Handoff-Pflicht.
Policy MUSS vor jeder nicht-trivialen Action ausgewertet werden.
Policy DARF nie schwächer sein als Browser- oder Plattformgrenzen.

4. Kernbegriffe

4.1 Principals

type PrincipalType = "user" | "agent" | "bridge" | "observer" | "system";

interface PolicyPrincipal {
  type: PrincipalType;
  id: string;
  roles?: string[];
  grants?: PolicyGrant[];
}

4.2 Grants

type PolicyGrant =
  | "observe"
  | "guide"
  | "draft"
  | "act"
  | "admin"
  | "read.sensitive"
  | "read.secret"
  | "write.sensitive"
  | "billing"
  | "identity"
  | "security";

Semantik

observe: UI lesen, aber nichts verändern
guide: Highlight/Fokus/Navigation ohne Seiteneffekt
draft: reversible Entwürfe oder Feldvorschläge
act: normale operative Actions
admin: privilegierte Actions
zusätzliche Grants regeln sensible Domänen und Daten

4.3 Datenklassen

type DataClass =
  | "public"
  | "internal"
  | "personal"
  | "sensitive"
  | "credential"
  | "secret"
  | "payment"
  | "legal";

4.4 Seiteneffektklassen

type SideEffectClass =
  | "none"
  | "local_ui"
  | "internal_persist"
  | "external_message"
  | "identity_change"
  | "billing_change"
  | "security_change"
  | "irreversible";

4.5 Policy-Entscheidungen

type PolicyEffect =
  | "allow"
  | "confirm"
  | "deny"
  | "handoff";

4.6 Begründungscodes

type PolicyReasonCode =
  | "grant_missing"
  | "route_denied"
  | "target_denied"
  | "risk_confirm"
  | "risk_blocked"
  | "sensitive_data"
  | "secret_data"
  | "credential_data"
  | "external_effect"
  | "privileged_action"
  | "user_activation_missing"
  | "human_actor_required"
  | "unsafe_retry"
  | "redaction_required"
  | "policy_default";

5. Policy-Dokument

interface PolicyDocument {
  modelVersion: "0.1";
  extension: "uicp.policy";
  profile?: string; // z. B. "[email protected]"

  defaults: PolicyDefaults;
  rules: PolicyRule[];

  redaction?: RedactionRule[];
  audit?: AuditPolicy;
  handoff?: HandoffPolicy;

  metadata?: Record<string, unknown>;
}

interface PolicyDefaults {
  onSafeRisk: PolicyEffect;       // RECOMMENDED: "allow"
  onConfirmRisk: PolicyEffect;    // RECOMMENDED: "confirm"
  onBlockedRisk: PolicyEffect;    // RECOMMENDED: "handoff"
  onUnknownAction: PolicyEffect;  // RECOMMENDED: "deny"
  onSensitiveRead: PolicyEffect;  // RECOMMENDED: "confirm"
  onSecretRead: PolicyEffect;     // RECOMMENDED: "deny"
}

5.1 Policy-Regeln

interface PolicyRule {
  id: string;
  enabled?: boolean;
  priority?: number; // higher wins

  when: PolicyPredicate;
  effect: PolicyEffect;

  obligations?: PolicyObligation[];
  reason?: string;
}

interface PolicyPredicate {
  actionIds?: string[];
  routeIds?: string[];
  stableIds?: string[];
  roles?: UIRole[];

  riskLevels?: RiskLevel[];
  riskTags?: RiskTag[];

  dataClasses?: DataClass[];
  sideEffectClasses?: SideEffectClass[];

  principals?: string[];          // principal.id
  principalTypes?: PrincipalType[];
  requiredGrants?: PolicyGrant[];

  executionModes?: ExecutionMode[];
}

5.2 Obligations

type PolicyObligation =
  | {
      type: "audit";
      level?: AuditLevel;
    }
  | {
      type: "redact";
      paths: string[];
      replacement?: string;
    }
  | {
      type: "limitExecutionModes";
      modes: ExecutionMode[];
    }
  | {
      type: "requireVerification";
      policy: "any" | "all";
      signals?: SuccessSignal[];
    }
  | {
      type: "requireUserActivation";
    }
  | {
      type: "requireHumanActor";
      reason?: string;
    }
  | {
      type: "maxAttempts";
      value: number;
    };

6. Policy-Kontext

interface PolicyContext {
  sessionId?: string;
  revision?: RevisionId;

  principal: PolicyPrincipal;

  actionId: ActionId;
  target?: {
    ref?: TargetRef;
    stableId?: StableId;
    role?: UIRole;
    name?: string;
    scopeId?: ScopeId;
    documentId?: DocumentId;
  };

  risk?: RiskDescriptor;
  dataClasses?: DataClass[];
  sideEffectClass?: SideEffectClass;

  executionMode?: ExecutionMode;
  routeId?: string;

  userActivation?: {
    isActive?: boolean;
    hasBeenActive?: boolean;
  };

  retryOfActionHandle?: string;
  attempt?: number;

  args?: Record<string, unknown>;
  metadata?: Record<string, unknown>;
}

7. Policy-Entscheidung

interface PolicyDecision {
  decision: PolicyEffect;
  reasonCodes: PolicyReasonCode[];

  obligations?: PolicyObligation[];
  effectiveExecutionModes?: ExecutionMode[];

  redactions?: RedactionPlan[];
  audit?: AuditDirective;

  cacheTtlMs?: number;
}

interface RedactionPlan {
  path: string;
  replacement: string;
}

type AuditLevel = "none" | "decision" | "result" | "full";

interface AuditDirective {
  level: AuditLevel;
  emitRecord: boolean;
}

8. Nachrichtentypen

8.1 `uicp.policy.get`

Request

interface PolicyGetPayload {}

Response: `uicp.policy.document`

interface PolicyDocumentPayload {
  policy: PolicyDocument;
  revision?: string;
}

8.2 `uicp.policy.evaluate`

Request

interface PolicyEvaluatePayload {
  context: PolicyContext;
}

Response: `uicp.policy.decision`

interface PolicyDecisionPayload {
  contextHash?: string;
  decision: PolicyDecision;
}

8.3 `uicp.policy.changed`

Event

interface PolicyChangedPayload {
  revision: string;
  reason?: "role_change" | "tenant_change" | "feature_flag" | "policy_update" | string;
  policy: PolicyDocument;
}

8.4 `uicp.policy.audit`

Event

interface PolicyAuditPayload {
  record: PolicyAuditRecord;
}

interface PolicyAuditRecord {
  auditId: string;
  ts: string;
  sessionId?: string;

  principal: PolicyPrincipal;
  actionId?: ActionId;
  target?: TargetRef;

  decision: PolicyEffect;
  reasonCodes: PolicyReasonCode[];

  obligations?: PolicyObligation[];
  sideEffectClass?: SideEffectClass;

  outcome?: "preflight" | "granted" | "confirmed" | "executed" | "failed" | "denied" | "handoff";
  stateRevision?: RevisionId;

  metadata?: Record<string, unknown>;
}

9. Auswertungsreihenfolge

Ein Policy Executor MUSS Entscheidungen in dieser Reihenfolge ableiten:

Explizite Deny-Regeln
Grant-Prüfung
Target-/Route-Blocklisten
Datenklassen und Redaktionspflicht
Risk Level und Risk Tags
Seiteneffektklasse
User-Activation-/Human-Actor-Pflichten
Defaults

Empfohlene sichere Baseline

safe + ausreichende Grants → allow
confirm → confirm
blocked → handoff
secret/credential lesen ohne Spezialgrant → deny
nicht-idempotenter Retry bei sideEffectState="unknown" → deny oder handoff

10. Redaktionsmodell

Redaktion MUSS getrennt von Action-Zulässigkeit modelliert werden.

interface RedactionRule {
  id: string;
  when: {
    dataClasses?: DataClass[];
    stableIds?: StableId[];
    routeIds?: string[];
  };
  applyTo: Array<"snapshot" | "signal" | "returnValue" | "audit">;
  replacement?: string; // default: "[REDACTED]"
}

Regeln

Redaktion DARF ein Objekt teilweise maskieren, ohne die Action selbst zu verbieten.
credential und secret SOLLTEN standardmäßig redaktiert werden.
Audit-Daten SOLLTEN stärker redaktiert werden als Laufzeitdaten.

11. Handoff-Modell

Browser und Plattform verlangen in manchen Fällen echte Nutzerinteraktion oder vertrauenswürdige Eingaben. Deshalb ist handoff kein Fehler, sondern ein normaler Policy-Ausgang. navigator.userActivation liefert den Aktivierungszustand, Event.isTrusted unterscheidet Browser-/User-Agent-generierte Events von dispatchEvent()-Events, und HTMLElement.click() ersetzt nicht automatisch jede user-activation-gated Situation. ([MDN Web Docs][2])

interface HandoffPolicy {
  triggers: HandoffTrigger[];
  defaultMessage?: string;
}

type HandoffTrigger =
  | "user_activation_required"
  | "credential_entry"
  | "payment_approval"
  | "external_auth"
  | "captcha"
  | "legal_acknowledgement"
  | "ambiguity"
  | "security_sensitive";

Regeln

Wenn eine Obligation requireUserActivation enthält und userActivation.isActive !== true, MUSS die Entscheidung mindestens handoff sein.
Wenn requireHumanActor aktiv ist, DARF keine autonome Ausführung folgen.
handoff SOLLTE einen menschenlesbaren Grundtext erzeugen können.

12. Minimaler Konformitätsumfang

Eine konforme [email protected]-Implementierung MUSS:

uicp.policy.get und uicp.policy.evaluate unterstützen,
PolicyDocument und PolicyDecision validieren,
confirm, deny, handoff und allow unterscheiden,
Redaction Rules anwenden können,
Audit-Records erzeugen können,
blocked Risk härter behandeln als confirm.

13. Beispiel-Policy

{
  "modelVersion": "0.1",
  "extension": "uicp.policy",
  "profile": "[email protected]",
  "defaults": {
    "onSafeRisk": "allow",
    "onConfirmRisk": "confirm",
    "onBlockedRisk": "handoff",
    "onUnknownAction": "deny",
    "onSensitiveRead": "confirm",
    "onSecretRead": "deny"
  },
  "rules": [
    {
      "id": "deny-credentials",
      "priority": 100,
      "when": {
        "dataClasses": ["credential", "secret"]
      },
      "effect": "deny",
      "obligations": [
        {
          "type": "audit",
          "level": "decision"
        }
      ]
    },
    {
      "id": "confirm-create-video",
      "priority": 50,
      "when": {
        "actionIds": ["video.create"]
      },
      "effect": "confirm",
      "obligations": [
        {
          "type": "requireVerification",
          "policy": "all",
          "signals": [
            { "kind": "route.changed", "pattern": "/videos/:id" },
            { "kind": "toast.contains", "text": "erstellt" }
          ]
        },
        {
          "type": "audit",
          "level": "result"
        }
      ]
    }
  ],
  "redaction": [
    {
      "id": "mask-secrets",
      "when": {
        "dataClasses": ["secret", "credential"]
      },
      "applyTo": ["snapshot", "audit", "returnValue"],
      "replacement": "[REDACTED]"
    }
  ],
  "audit": {
    "level": "result",
    "includeArgs": false,
    "includeReturnValue": false
  },
  "handoff": {
    "triggers": [
      "user_activation_required",
      "credential_entry",
      "payment_approval",
      "external_auth"
    ],
    "defaultMessage": "Bitte übernimm diesen Schritt selbst."
  }
}

Normative Referenzen

[UIAP-CORE] UIAP Core v0.1
[RFC2119] Key words for use in RFCs to Indicate Requirement Levels, BCP 14

Security Considerations

Policy-Dokumente SOLLTEN nur von vertrauenswürdigen Quellen geladen werden.
Eine lokale deny-Entscheidung MUSS immer Vorrang haben und DARF NICHT von einem externen Service überstimmt werden.
Audit-Logs MÜSSEN manipulationssicher gespeichert werden.
Sensitive Daten MÜSSEN vor der Protokollierung redaktiert werden.
requireUserActivation SOLLTE für alle irreversiblen oder extern wirksamen Aktionen gesetzt sein.

Changelog

Version	Datum	Änderungen
0.1	2026-03-27	Initialer Entwurf

UIAP Policy Extension

UIAP Policy Extension v0.1

1. Zweck

Normative Begriffe

2. Kennung und Aushandlung

3. Geltung und Grundsätze

4. Kernbegriffe

4.1 Principals

4.2 Grants

Semantik

4.3 Datenklassen

4.4 Seiteneffektklassen

4.5 Policy-Entscheidungen

4.6 Begründungscodes

5. Policy-Dokument

5.1 Policy-Regeln

5.2 Obligations

6. Policy-Kontext

7. Policy-Entscheidung

8. Nachrichtentypen

8.1 uicp.policy.get

Request

Response: uicp.policy.document

8.2 uicp.policy.evaluate

Request

Response: uicp.policy.decision

8.3 uicp.policy.changed

Event

8.4 uicp.policy.audit

Event

9. Auswertungsreihenfolge

Empfohlene sichere Baseline

10. Redaktionsmodell

Regeln

11. Handoff-Modell

Regeln

12. Minimaler Konformitätsumfang

13. Beispiel-Policy

Normative Referenzen

Security Considerations

Changelog

8.1 `uicp.policy.get`

Response: `uicp.policy.document`

8.2 `uicp.policy.evaluate`

Response: `uicp.policy.decision`

8.3 `uicp.policy.changed`

8.4 `uicp.policy.audit`