@fabricorg/sdui-release 0.3.0 → 0.6.0

package/dist/index.d.ts

@@ -1,265 +1,9 @@
+import { S as SduiAuthorizationGrants, a as SduiComponentPack, b as SduiDocument, c as SduiFragment, d as SduiRelease, e as SduiTokenSet, f as SduiValidationInput, g as SduiValidationResult, R as ResolvedSduiComponentPack } from './contracts-4fL-Yh38.js';
+export { E as EffectiveFragmentGrant, h as ExperienceIntentRoute, i as ExperienceViewRoute, j as RELEASE_CHANNEL_POINTER_FORMAT_VERSION, k as ReleaseChannelPointer, l as ReleaseCryptoPort, m as ReleaseGenerationStore, n as ReleaseTrustStore, o as ReleaseVerificationKey, p as SDUI_COMPONENT_PACK_FORMAT_VERSION, q as SDUI_DOCUMENT_FORMAT_VERSION, r as SDUI_RELEASE_FORMAT_VERSION, s as SDUI_RELEASE_V3_FORMAT_VERSION, t as SDUI_TOKEN_SET_FORMAT_VERSION, u as SduiActionRef, v as SduiCapabilityRef, w as SduiComponentDefinition, x as SduiComponentPackReference, y as SduiFinding, z as SduiFindingCode, A as SduiFragmentValue, B as SduiReleaseV3, C as SduiToken, D as SduiTokenSetReference, F as SduiTokenType, V as VerifySignedExperienceArtifactInput, G as activateReleaseChannelPointer, H as assertReleaseChannelPointer, I as assertSduiReleaseV3, J as canonicalizeJcs, K as verifySignedExperienceArtifact, L as verifySignedExperienceRelease } from './contracts-4fL-Yh38.js';
+import { UsageContract } from '@fabricorg/gen-capability';
 import { PortableJsonSchema } from '@fabricorg/platform';
 export { JsonValue } from '@fabricorg/platform';
-import { UsageContractDocument } from '@fabricorg/gen-capability';
-import { AssemblyLockfile } from '@fabricorg/assembly';
-
-/**
- * Version of the SDUI document contract. A vertical negotiates on this, not on
- * this package's version, and it moves only when the serialized shape changes.
- */
-declare const SDUI_DOCUMENT_FORMAT_VERSION: 1;
-/**
- * Version of the SDUI token-set contract.
- */
-declare const SDUI_TOKEN_SET_FORMAT_VERSION: 1;
-/**
- * Version of the SDUI component-pack contract.
- */
-declare const SDUI_COMPONENT_PACK_FORMAT_VERSION: 1;
-/**
- * Version of the promoted SDUI release contract.
- */
-declare const SDUI_RELEASE_FORMAT_VERSION: 2;
-/**
- * A capability read reference embedded in fragment props. The `capability://`
- * scheme ties a data binding to a published view; the host resolves it through
- * `ProjectionHost`, never through a direct query.
- */
-interface SduiCapabilityRef {
-    $ref: `capability://${string}`;
-}
-/**
- * A value that may appear in fragment props: a JSON literal, an array, an
- * object, or a `capability://` read reference. Direct mutation endpoints,
- * API URLs, or code strings are not valid fragment values.
- */
-type SduiFragmentValue = string | number | boolean | null | SduiFragmentValue[] | SduiCapabilityRef | {
-    [key: string]: SduiFragmentValue;
-};
-/**
- * An action declared on a fragment. The `intent` must be a `capability://`
- * reference to a published action intent; the host dispatches it through
- * `PlatformHost`, preserving governance. A bare endpoint URL, function name,
- * or inline script is a mutation bypass and is rejected.
- */
-interface SduiActionRef {
-    intent: `capability://${string}`;
-    params?: Record<string, SduiFragmentValue>;
-}
-/**
- * A node in an SDUI document tree. A fragment either renders a component from
- * a declared pack, binds data from a capability view, or both. Actions on a
- * fragment are always capability action-intent references — never direct
- * mutations.
- */
-interface SduiFragment {
-    /** Unique identifier within the document. */
-    id: string;
-    /** Namespaced component (`pack.Component`) or a core component name. */
-    component?: string;
-    /** Props for the component; values may be literals or capability refs. */
-    props?: Record<string, SduiFragmentValue>;
-    /** Named slot this fragment fills in its parent component. */
-    slot?: string;
-    /** A capability view reference for data-driven fragments. */
-    dataRef?: `capability://${string}`;
-    /** Action handlers; every entry must be a capability action-intent reference. */
-    actions?: Record<string, SduiActionRef>;
-    /** Child fragments. */
-    children?: SduiFragment[];
-}
-type SduiTokenType = "color" | "spacing" | "fontSize" | "fontWeight" | "radius" | "border" | "shadow";
-interface SduiToken {
-    type: SduiTokenType;
-    value: string;
-    description?: string;
-}
-/**
- * A versioned set of design tokens. Tokens are semantic, not literal CSS — a
- * renderer maps them to its own platform. Two channels consuming the same
- * token set apply the same visual intent through different renderings.
- */
-interface SduiTokenSet {
-    formatVersion: typeof SDUI_TOKEN_SET_FORMAT_VERSION;
-    name: string;
-    version: string;
-    tokens: Record<string, SduiToken>;
-}
-interface SduiComponentDefinition {
-    /** Roles this component implements (for adoption-binding validation). */
-    implements?: string[];
-    /** JSON Schema for component props. */
-    propsSchema?: PortableJsonSchema;
-    /** Named slots this component accepts. */
-    slots?: string[];
-}
-/**
- * A versioned pack of SDUI components. Compatible with the adoption-bindings
- * `ComponentPackManifest` but adds prop schemas and slot declarations so a
- * document can be validated without a renderer.
- */
-interface SduiComponentPack {
-    formatVersion: typeof SDUI_COMPONENT_PACK_FORMAT_VERSION;
-    pack: string;
-    namespace: string;
-    version: string;
-    /** SHA-256 digest of the published component-pack artifact. */
-    artifactDigest: string;
-    /**
-     * Where this pack is loaded from when it is delivered as a federated
-     * remote. The artifact digest identifies the pack that was reviewed; this
-     * is what a shell actually executes, so validation requires the two to be
-     * locked together or the review covers something other than what runs.
-     */
-    remote?: SduiComponentPackRemote;
-    components: Record<string, SduiComponentDefinition>;
-}
-/** Delivery binding for a federated component pack. */
-interface SduiComponentPackRemote {
-    /** Remote entry URL the shell loads. */
-    entry: string;
-    /** Subresource-integrity value for that entry, e.g. `sha384-…`. */
-    integrity: string;
-    /** Exposed module path keyed by the component name it provides. */
-    exposes: Record<string, string>;
-}
-interface SduiComponentPackReference {
-    pack: string;
-    namespace: string;
-    /** Semver range, e.g. `^1.0.0`. */
-    range: string;
-}
-interface SduiTokenSetReference {
-    name: string;
-    version: string;
-}
-/**
- * A versioned SDUI document: a tree of fragments, a token-set reference, and
- * the component packs it depends on. This is the build-time input; the release
- * is the validated, resolved output.
- */
-interface SduiDocument {
-    formatVersion: typeof SDUI_DOCUMENT_FORMAT_VERSION;
-    name: string;
-    version: string;
-    /** The tree rendered when no variant is selected. */
-    root: SduiFragment;
-    /**
-     * Alternative trees a compositor may select at request time, for experiment
-     * arms and personalization. Every variant is enumerated here and validated
-     * against the same grants as `root`, and all of them are covered by the
-     * release digest.
-     *
-     * Enumeration is what makes selection safe. A selector that can produce a
-     * tree outside this set cannot be validated at promotion, so "selection may
-     * never widen grants" would be unenforceable rather than merely unenforced.
-     */
-    variants?: SduiVariant[];
-    tokenSet: SduiTokenSetReference;
-    componentPacks: SduiComponentPackReference[];
-}
-/** One selectable alternative to a document's default tree. */
-interface SduiVariant {
-    /** Stable key the compositor matches on. Unique within the document. */
-    id: string;
-    /** The audience or experiment arm this arm serves. */
-    description?: string;
-    root: SduiFragment;
-}
-interface ResolvedSduiComponentPack {
-    pack: string;
-    namespace: string;
-    version: string;
-    range: string;
-    artifactDigest: string;
-    /**
-     * The locked delivery binding, carried onto the release so the digest
-     * identifies which remote a channel is expected to load. Omitting it would
-     * let two releases differing only in their remote share a digest.
-     */
-    remote?: SduiComponentPackRemote;
-}
-/**
- * A promoted, validated, immutable SDUI release. It bundles a document, a
- * resolved token set, and locked component packs. Two channels (web, mobile,
- * CLI) can consume the same release and render it through their own renderers
- * while reads and actions remain capability references.
- */
-interface SduiRelease {
-    formatVersion: typeof SDUI_RELEASE_FORMAT_VERSION;
-    /** SHA-256 of the canonical document, token set, resolved packs, grants, and assembly identity. */
-    releaseDigest: string;
-    /** Approved application assembly this release was validated against. */
-    assemblyDigest: string;
-    document: SduiDocument;
-    tokenSet: SduiTokenSet;
-    componentPacks: ResolvedSduiComponentPack[];
-    grants: SduiAuthorizationGrants;
-}
-type SduiFindingCode = "unknown_component" | "incompatible_pack" | "unauthorized_data_ref" | "denied_view_ref" | "mutation_bypass" | "denied_intent_ref" | "intent_action_not_found" | "invalid_fragment" | "invalid_action_ref" | "unknown_token" | "duplicate_fragment_id" | "invalid_token_set" | "invalid_component_pack" | "invalid_document" | "missing_token_set" | "missing_component_pack" | "component_pack_not_in_assembly" | "capability_contract_not_in_assembly" | "duplicate_variant_id" | "fragment_grant_exceeds_release" | "remote_not_locked";
-interface SduiFinding {
-    code: SduiFindingCode;
-    path: string;
-    message: string;
-}
-interface SduiValidationResult {
-    valid: boolean;
-    findings: SduiFinding[];
-    release: SduiRelease | undefined;
-}
-/**
- * Explicit capability references authorized for an SDUI release.
- *
- * The presence of a view or action in a supplied usage contract proves that
- * the capability publishes it, not that this document may use it. The
- * experience host must therefore provide both grant lists explicitly.
- */
-interface SduiAuthorizationGrants {
-    /** Full `capability://namespace/view` references allowed in data bindings. */
-    views: readonly string[];
-    /** Full `capability://namespace/intent` references allowed in actions. */
-    intents: readonly string[];
-    /**
-     * Per-fragment narrowing, keyed by fragment id.
-     *
-     * The release-wide lists above are the ceiling. A listed fragment may use
-     * only the references named for it, and the narrowing is inherited by that
-     * fragment's children, so a page assembled from several teams' fragments
-     * gets least privilege rather than the union of everything any of them
-     * needs. A fragment entry can only ever narrow: naming a reference outside
-     * the release-wide list is an authoring error and is reported rather than
-     * silently granted.
-     *
-     * Keys are fragment ids, which are unique within a tree but may repeat
-     * across variants, so two variants using the same fragment id share one
-     * entry. Give them distinct ids when they need distinct narrowing. This
-     * cannot widen either fragment, since narrowing stays an intersection.
-     */
-    fragments?: Record<string, SduiFragmentGrants>;
-}
-/** References one fragment subtree may use, drawn from the release-wide lists. */
-interface SduiFragmentGrants {
-    views?: readonly string[];
-    intents?: readonly string[];
-}
-interface SduiValidationInput {
-    document: SduiDocument;
-    tokenSet: SduiTokenSet;
-    /** Available component packs for version resolution. */
-    componentPacks: SduiComponentPack[];
-    /** Capability contracts available for data-ref and action validation. */
-    contracts: UsageContractDocument[];
-    /**
-     * Explicit authorization grants for every capability view and action
-     * reference used by the document. Contract membership alone never grants
-     * access.
-     */
-    grants: SduiAuthorizationGrants;
-    /** Approved resolved application composition. */
-    assembly: AssemblyLockfile;
-    /** Core component vocabulary every renderer implements. */
-    coreComponents?: readonly string[];
-}
+import '@fabricorg/assembly';
 
 declare function assertSduiTokenSet(value: unknown, path?: string): asserts value is SduiTokenSet;
 declare function assertSduiComponentPack(value: unknown, path?: string): asserts value is SduiComponentPack;
@@ -298,6 +42,11 @@ declare function computeReleaseDigest(document: SduiDocument, tokenSet: SduiToke
 /** Reject promoted release content that no longer matches its immutable digest. */
 declare function assertSduiReleaseIntegrity(release: SduiRelease): void;
 
+declare function parseCapabilityRef(ref: string): {
+    namespace: string;
+    name: string;
+} | undefined;
+
 /**
  * A channel is a rendering target (web, mobile, CLI). A channel consumes a
  * validated release and resolves capability references through its own host
@@ -327,8 +76,118 @@ interface SduiChannelConsumptionResult {
  * components are resolved from the release's locked packs, not the channel.
  */
 declare function createSduiChannel(id: string, coreComponents: readonly string[]): SduiChannel;
+/**
+ * The subject a channel implementation supplies to be certified.
+ *
+ * `validRelease` must be a genuinely promoted release, and it must use
+ * `unimplementedCoreComponent`, which the channel must not implement. The suite
+ * certifies that a channel *reports* what it cannot render, so the fixture has
+ * to be one that requires reporting: consuming `validRelease` is therefore
+ * expected to come back incompatible. The suite derives its own tampered and
+ * unpromoted variants from it, so an implementer never has to hand-construct an
+ * invalid release correctly.
+ */
+interface SduiChannelConformanceSubject {
+    channel: SduiChannel;
+    validRelease: SduiRelease;
+    /** A core component the channel does not implement, used to prove it reports rather than renders. */
+    unimplementedCoreComponent: string;
+}
+interface SduiChannelCheck {
+    id: "fabric.sdui-channel.verified-release.v1" | "fabric.sdui-channel.tampered-release-denial.v1" | "fabric.sdui-channel.unpromoted-document-denial.v1" | "fabric.sdui-channel.reports-missing-vocabulary.v1" | "fabric.sdui-channel.consumption-is-pure.v1";
+    run(subject: SduiChannelConformanceSubject): Promise<string[]>;
+}
+interface SduiChannelConformanceResult {
+    passed: boolean;
+    checks: Array<{
+        id: SduiChannelCheck["id"];
+        status: "passed" | "failed";
+        evidence: string[];
+        error?: string;
+    }>;
+}
+/**
+ * The suite any channel must pass before it is allowed to render.
+ *
+ * The governed path holds only if a channel refuses anything that is not a
+ * promoted, digest-verified release. A renderer that accepts a composed
+ * document directly never runs `validateSduiRelease`, so grants, variants and
+ * locked remotes apply to nothing. That is the single failure this suite
+ * exists to make impossible to ship.
+ */
+declare function sduiChannelChecks(): readonly SduiChannelCheck[];
+/** Run every channel check, returning each result rather than throwing on the first. */
+declare function runSduiChannelChecks(subject: SduiChannelConformanceSubject): Promise<SduiChannelConformanceResult>;
+
+/**
+ * What an actor holds, as the surrounding system already models it.
+ *
+ * These come from wherever entitlements are administered — a plan, a licence,
+ * a role assignment, an identity provider's scopes. Fabric does not administer
+ * them; it decides what they add up to.
+ */
+interface ActorEntitlements {
+    permissions?: readonly string[];
+    entitlements?: readonly string[];
+    featureFlags?: readonly string[];
+}
+/** A capability the actor cannot use, and the first requirement they are missing. */
+interface WithheldCapability {
+    namespace: string;
+    missing: {
+        kind: "permission" | "entitlement" | "featureFlag";
+        name: string;
+    };
+}
+interface DerivedGrants {
+    grants: SduiAuthorizationGrants;
+    /** Capabilities deliberately left out, so an absent navigation entry is explainable. */
+    withheld: WithheldCapability[];
+}
+interface DeriveGrantsOptions {
+    /**
+     * Restrict the result to references this document actually binds.
+     *
+     * Supply it whenever the grants will be promoted. Grants are not only a
+     * navigation hint: `validateSduiRelease` carries them onto the release
+     * unexamined, and promotion compiles a signed route for every one, so a
+     * surplus grant becomes a signed route to a capability the screen never
+     * uses. Scoping to the document is what keeps the release's exposed surface
+     * equal to what it actually renders.
+     */
+    document?: SduiDocument;
+    /**
+     * What to do with a capability that declares no requirements at all.
+     *
+     * Defaults to `"withhold"`. Requirements are optional metadata, so silence
+     * is the common case, and reading silence as "available to everyone" makes
+     * the default open. Pass `"grant"` only for a contract set you have decided
+     * is unrestricted.
+     */
+    undeclaredRequirements?: "withhold" | "grant";
+}
+/**
+ * Derive release grants from what an actor holds.
+ *
+ * A shell has to decide what to show. If it answers that from its own
+ * configuration while grants are hand-maintained somewhere else and enforcement
+ * happens in a third place, the three drift, and the one the user sees drifts
+ * from the one that enforces. Deriving grants here makes navigation a
+ * projection of the same declarations rather than a parallel guess at them.
+ *
+ * This is navigation-shaped, not enforcement. It decides what a viewer is
+ * offered; `PlatformHost` still re-checks authority when an action executes and
+ * `ProjectionHost` still authorizes every query, so stale navigation is a
+ * cosmetic problem rather than a security one. Nothing here is a gate.
+ *
+ * A capability contributes nothing unless every requirement it declares is
+ * held. Partial access is not modelled on purpose: a capability that publishes
+ * a view behind a permission the actor lacks has said the whole capability is
+ * gated, and inferring finer structure from silence would be inventing policy.
+ */
+declare function deriveAuthorizationGrants(contracts: readonly UsageContract[], held: ActorEntitlements, options?: DeriveGrantsOptions): DerivedGrants;
 
 declare const SDUI_DOCUMENT_JSON_SCHEMA: PortableJsonSchema;
 declare const SDUI_RELEASE_JSON_SCHEMA: PortableJsonSchema;
 
-export { type ResolvedSduiComponentPack, SDUI_COMPONENT_PACK_FORMAT_VERSION, SDUI_DOCUMENT_FORMAT_VERSION, SDUI_DOCUMENT_JSON_SCHEMA, SDUI_RELEASE_FORMAT_VERSION, SDUI_RELEASE_JSON_SCHEMA, SDUI_TOKEN_SET_FORMAT_VERSION, type SduiActionRef, type SduiAuthorizationGrants, type SduiCapabilityRef, type SduiChannel, type SduiChannelConsumptionResult, type SduiComponentDefinition, type SduiComponentPack, type SduiComponentPackReference, type SduiDocument, type SduiFinding, type SduiFindingCode, type SduiFragment, type SduiFragmentValue, type SduiRelease, type SduiToken, type SduiTokenSet, type SduiTokenSetReference, type SduiTokenType, type SduiValidationInput, type SduiValidationResult, assertSduiAuthorizationGrants, assertSduiComponentPack, assertSduiDocument, assertSduiFragment, assertSduiRelease, assertSduiReleaseIntegrity, assertSduiReleaseValid, assertSduiTokenSet, computeReleaseDigest, createSduiChannel, validateSduiRelease };
+export { type ActorEntitlements, type DerivedGrants, ResolvedSduiComponentPack, SDUI_DOCUMENT_JSON_SCHEMA, SDUI_RELEASE_JSON_SCHEMA, SduiAuthorizationGrants, type SduiChannel, type SduiChannelCheck, type SduiChannelConformanceResult, type SduiChannelConformanceSubject, type SduiChannelConsumptionResult, SduiComponentPack, SduiDocument, SduiFragment, SduiRelease, SduiTokenSet, SduiValidationInput, SduiValidationResult, type WithheldCapability, assertSduiAuthorizationGrants, assertSduiComponentPack, assertSduiDocument, assertSduiFragment, assertSduiRelease, assertSduiReleaseIntegrity, assertSduiReleaseValid, assertSduiTokenSet, computeReleaseDigest, createSduiChannel, deriveAuthorizationGrants, parseCapabilityRef, runSduiChannelChecks, sduiChannelChecks, validateSduiRelease };