@fabricorg/sdui-release 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,125 @@
+# Changelog
+
+## 0.3.0
+
+### Minor Changes
+
+- 89982ba: Lock federated component-pack delivery. A component pack may declare a `remote` with its entry URL,
+  a subresource-integrity value, and its exposed modules; `resolveAssembly` locks that binding in the
+  lockfile alongside the artifact digest, and `validateSduiRelease` rejects a release whose declared
+  remote does not match the locked one, or which adds or drops a remote the assembly did not.
+
+  A federated pack executes whatever its remote entry serves at load time, so an approved artifact
+  digest describes the pack that was reviewed rather than the code that runs. Locking the entry and
+  its integrity closes that gap without Fabric loading anything: the shell verifies integrity against
+  the lockfile before executing. The field is optional, so packs delivered any other way are unchanged.
+
+- 89982ba: Add enumerated document variants and per-fragment grant narrowing.
+
+  `SduiDocument.variants` declares every alternative tree a compositor may select at request time.
+  Each variant is walked against the same grants as the default tree and is covered by the release
+  digest, so selection can never widen what a viewer may see or do. Enumeration at promotion is what
+  makes that invariant enforceable: a selector able to produce a tree outside the release cannot be
+  validated. Fragment ids are unique within a tree rather than across the document, since only one
+  variant renders.
+
+  `SduiAuthorizationGrants.fragments` narrows a fragment subtree to a subset of the release-wide
+  grants, inherited by its children. Narrowing is an intersection, so a fragment entry can never widen,
+  and naming a reference the release does not grant is reported as `fragment_grant_exceeds_release`
+  rather than silently ignored. A page assembled from several teams' fragments gets least privilege
+  instead of the union of everything any of them needs.
+
+### Patch Changes
+
+- 6f5471b: Close the gaps an independent review found in the grant, remote and identity work.
+
+  A capability reference object was treated as a leaf, so a granted reference could shield ungranted
+  ones parked beside it on the same object; sibling keys are now walked. Prop recursion is depth
+  bounded, so cyclic programmatic input reports a finding instead of exhausting the stack. Federated
+  remotes now compare their exposed-module mapping, not only entry and integrity, and the locked remote
+  is carried onto the promoted release so two releases differing only in their remote cannot share a
+  digest. Pack lookup matches full pack identity rather than namespace and name alone, and a stored
+  lockfile that declares one pack or capability twice is rejected rather than resolved by first match.
+
+  Grant digests omit `variants` and `fragments` when absent, so a release that declares neither digests
+  exactly as it did before those fields existed and previously promoted releases keep verifying.
+  Variants are hashed in id order, so reordering the same set no longer churns the digest. Fragment
+  grants written as a `{ __proto__: … }` object literal are rejected, because that sets the prototype
+  rather than creating the entry and the narrowing would silently disappear.
+
+  `assertActorClaimsCoverScope` no longer fails open: an invalid clock is rejected instead of making
+  every temporal comparison false, timestamps must be RFC 3339 with an explicit offset so a credential
+  cannot expire at different instants on different hosts, and `spaceIds` must be an array of strings so
+  a bare string cannot reach substring matching where `"space_10"` would cover `"space_1"`.
+
+- 89982ba: Check capability references at every position a prop value can occupy. Grant enforcement previously
+  ran only where a reference sat directly at a prop key: a reference nested inside an array was
+  recursed into as if it were a props record, matched no branch, and was never checked, so a published
+  but ungranted view passed validation with no findings. Arrays are the ordinary shape for list props
+  such as `rows` and `items`, so this reached the common case rather than an edge case. Prop values now
+  route through a single `checkValue` that resolves references at any depth, which closes the same gap
+  in action `params`.
+- Updated dependencies
+- Updated dependencies [89982ba]
+- Updated dependencies [6f5471b]
+  - @fabricorg/gen-capability@0.5.0
+  - @fabricorg/assembly@0.3.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 4e585a4: Close final production-maturity correctness gaps: expired leases can no longer be renewed,
+  saga parent transitions are serialized, atomic, terminal-safe, and retry-idempotent by lifecycle identity, hydrated
+  projections must meet requested checkpoints, and SDUI releases accept components only from
+  resolved document packs. The release gate now verifies every package and public subpath in
+  isolated ESM, CommonJS, and TypeScript consumers.
+- 1ba3a9e: Require explicit view and action-intent grants during SDUI release validation,
+  and reject experience intents that do not resolve to a declared governed action.
+- 8e9a571: Added versioned SDUI document, fragment, token-set, component-pack, and
+  promoted release contracts validated independently of any renderer. Every
+  promoted release requires an integrity-verified assembly lockfile and rejects
+  usage contracts or component-pack artifacts outside that approved composition.
+  Release format version 2 binds the assembly digest and exact authorization
+  grants into its immutable digest. Channels reject release content changed after
+  promotion or loaded with an invalid release structure or format, while reads
+  and actions remain capability references.
+- e6aede7: Split the SDUI release implementation into cohesive private modules without
+  changing public exports, and centralize semver range resolution by importing
+  from `@fabricorg/assembly` instead of duplicating the zero-dependency semver
+  implementation. Adds `@fabricorg/assembly` as a runtime dependency.
+
+### Patch Changes
+
+- Updated dependencies [62dd1ca]
+- Updated dependencies [b932767]
+  - @fabricorg/assembly@0.2.0
+  - @fabricorg/gen-capability@0.4.1
+
+### Additional release notes
+
+- Split the single-file implementation into cohesive private modules
+  (types, helpers, structural, digest, capabilities, walker, channel, schemas,
+  validate) without changing any public exports.
+- Centralized semver range resolution by importing `parseSemverRange` and
+  `resolveVersionRange` from `@fabricorg/assembly` instead of duplicating the
+  zero-dependency semver implementation.
+- Require explicit view and action-intent grants during SDUI release validation,
+  so published contract membership is not treated as authorization.
+- Validate that every declared experience action intent resolves to an action in
+  its capability contract.
+- Build the known-component vocabulary only from packs resolved by the document,
+  preventing undeclared supplied packs from authorizing unusable components.
+- Structurally validate persisted or network-loaded promoted releases before
+  recomputing their digest, including the release format version.
+
+## 0.1.0
+
+- Added versioned `SduiDocument`, `SduiFragment`, `SduiTokenSet`,
+  `SduiComponentPack`, and `SduiRelease` contracts.
+- Added `validateSduiRelease` build gate that rejects unknown components,
+  incompatible packs, unauthorized data references, and mutation bypasses.
+- Added `assertSduiReleaseValid` for throwing on the first invalid result.
+- Added `createSduiChannel` for multi-channel release consumption with core
+  component compatibility checks.
+- Added canonical SHA-256 release digests for deterministic release identity.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Fabric Pro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# `@fabricorg/sdui-release`
+
+Versioned SDUI document, fragment, token-set, component-pack, and promoted release
+contracts validated independently of any renderer.
+
+## What this package owns
+
+- **`SduiDocument`** — a versioned tree of fragments with a token-set reference and
+  declared component-pack ranges. `variants` enumerates every alternative tree a
+  compositor may select at request time; each is validated against the same
+  grants and covered by the release digest, which is what makes "selection may
+  never widen grants" enforceable rather than merely stated.
+- **`SduiFragment`** — a node that renders a component, binds data from a capability
+  view, and declares action handlers. Actions are always `capability://` references
+  to published action intents — never direct mutations.
+- **`SduiTokenSet`** — renderer-neutral design tokens (color, spacing, typography).
+  Two channels consuming the same token set apply the same visual intent through
+  different renderings.
+- **`SduiComponentPack`** — a versioned pack of components with prop schemas,
+  slot declarations, and the published artifact digest used by assembly. A
+  federated pack also declares its `remote`: the entry URL, a
+  subresource-integrity value, and its exposed modules. A federated pack executes
+  whatever its entry serves, so the artifact digest alone describes the pack that
+  was reviewed rather than the code that runs.
+- **`SduiRelease`** — a promoted, validated, immutable bundle with a canonical
+  SHA-256 digest. It includes the approved assembly identity and exact
+  authorization grants. Two channels (web, mobile, CLI) can consume the same
+  release while reads and actions remain capability references.
+
+## Validation
+
+`validateSduiRelease(input)` is the single build gate. It rejects:
+
+- **Unknown components** — a fragment references a component not in any declared
+  pack or the core vocabulary.
+- **Incompatible packs** — a component pack version does not satisfy the document's
+  declared range.
+- **Unapproved composition** — a pack artifact or usage contract does not match
+  the exact generated contract provenance and pack content in the supplied
+  assembly lockfile.
+- **Unauthorized data references** — a fragment or prop references a capability
+  view that no known contract publishes.
+- **Denied data references** — a published view is not present in the input's
+  explicit `grants.views` list. Contract visibility is not authorization. A
+  reference is resolved wherever it sits: at a prop key, inside an array, or
+  nested in either, since an array is the ordinary shape for a list prop.
+- **Grants that widen** — `grants.fragments` narrows a fragment subtree to a
+  subset of the release-wide grants, inherited by its children, so a page built
+  from several teams' fragments gets least privilege instead of the union.
+  Narrowing is an intersection, so a fragment entry can never widen, and naming
+  a reference the release does not grant is reported rather than ignored.
+- **Unlocked federated remotes** — a pack's declared remote does not match the
+  entry and integrity assembly locked, or a remote was added or dropped after
+  locking.
+- **Mutation bypasses** — an action handler is not a `capability://` reference or
+  references an intent no known capability declares.
+- **Denied intents** — a published action intent is not present in the input's
+  explicit `grants.intents` list.
+- **Broken intent declarations** — an experience action intent points to an
+  action ID the capability does not declare.
+
+It returns every finding rather than throwing, so one CI run tells a vertical
+everything it has to change. Use `assertSduiReleaseValid(input)` to throw on the
+first invalid result. Every release input must provide an integrity-verified
+assembly lockfile and both grant lists:
+
+```ts
+validateSduiRelease({
+  document,
+  tokenSet,
+  componentPacks,
+  contracts: usageContractDocuments,
+  assembly,
+  grants: {
+    views: ["capability://orders/summary"],
+    intents: ["capability://orders/submit"],
+  },
+});
+```
+
+An experience host or adoption-binding build can derive these references from
+its reviewed grants. Supplying a contract, or merely finding a matching
+capability reference, never authorizes a read or mutation.
+
+## Channel consumption
+
+`createSduiChannel(id, coreComponents)` creates a channel that consumes a
+validated release. The channel verifies the immutable release digest before it
+checks that every core component the document uses is in its vocabulary;
+pack-namespaced components are resolved from the release's locked packs. The
+integrity gate also validates the structure and format of releases loaded from
+persistence or a network before computing their digest. The
+channel never interprets or bypasses capability references — it renders
+fragments and forwards action intents through
+`ProjectionHost` (reads) and `PlatformHost` (actions).
+
+## Relationship to other packages
+
+This package depends on `@fabricorg/assembly` for shared semver resolution,
+`@fabricorg/gen-capability` for `UsageContractDocument` validation, and
+`@fabricorg/platform` for `PortableJsonSchema`. It does not depend on a renderer,
+a host, or a specific runtime. SDUI rendering, theming, and composition remain
+outside Fabric Platform, as established by ADR 0006.