Skip to content

Local model registry demo

Use File → Cloud Sources → Model registry to connect to a local registry, browse models and versions, open an IFC, edit it, and publish the saved model. The connection remains signed in while Cloud Sources is closed for editing. Model names, version names, publisher and publication time are the normal view; complete content fingerprints and declared package metadata are under Technical details.

Prepare the tools

Install the workspace dependencies using the repository's development setup. The browser needs the matching WASM runtime. pnpm build:wasm:fetch obtains an official prebuilt when it matches the checkout; otherwise build with pnpm build:wasm and the pinned Rust toolchain.

Make a Subsoil build from main and oras available in your terminal. Follow its browser application setup for client and callback registration. The connector is named oci-registry; Subsoil is the demo backend. Browser sign-in and sharing require the session extensions described below, in addition to standard OCI distribution.

These commands use only the public hello-wall.ifc fixture already in the repository. Run them from the IFClite repository root. Choose passwords when prompted:

subsoil user add --data build/registry-demo/store writer --grant project/model:pull,push
subsoil user add --data build/registry-demo/store reader --grant project/model:pull
subsoil serve --data build/registry-demo/store --listen 127.0.0.1:5000 \
  --oauth-client-id ifc-lite \
  --oauth-redirect-uri http://localhost:3000/oauth/registry/callback \
  --oauth-redirect-uri http://127.0.0.1:3000/oauth/registry/callback

Keep that server running. In another terminal, publish the sample through the standard OCI client using the writer's password:

oras login --plain-http --registry-config build/registry-demo/oras-auth.json \
  127.0.0.1:5000 --username writer
oras push --plain-http --registry-config build/registry-demo/oras-auth.json \
  --artifact-type application/vnd.ifc-lite.ifc.v1 \
  --annotation org.opencontainers.image.title="Hello wall" \
  127.0.0.1:5000/project/model:issued \
  apps/viewer/public/samples/hello-wall.ifc:application/x-step

Artifacts, the registry store and the selected ORAS credentials file stay in ignored build/. Keep credentials out of commits.

Run the browser flow

VITE_REGISTRY_ENABLED=true IFC_REGISTRY_TARGET=http://127.0.0.1:5000 pnpm dev

Open the local URL printed by Vite, normally http://localhost:3000. Register that exact viewer origin and callback path with the registry. If Vite uses another port, restart the registry with its matching --oauth-redirect-uri.

  1. Open File → Cloud Sources, expand Model registry, and paste http://localhost:5000 into Registry address. Click Sign in to registry. A popup opens on the registry's own address. Sign in there as the writer and approve access; the viewer never asks for or receives the password. Allow popups for the viewer if your browser blocks this window.
  2. Choose the model and version from the lists. Publication details identify the authenticated publisher and time when the registry recorded them. Click Open model and close Cloud Sources. If models are already loaded, confirm Replace session; this replaces every current model and discards unpublished edits. Cancel to keep the current session.
  3. Select a wall, open Author → Model, and edit Name in the Model inspector. Press Tab to apply the edit.
  4. Reopen Cloud Sources → Model registry. The connection remains signed in. Enter a fresh version name and click Publish edited model.
  5. Click Open saved version. Inspect the edited property and geometry to confirm the saved IFC was received again. The fetch uses the exact manifest digest internally.
  6. Sign out and use the registry popup to connect as the reader. Models and versions remain browsable; publishing is disabled and the server also enforces the restriction.

A complete model address such as http://localhost:5000/project/model:issued preselects that model and version. OCI references (localhost:5000/project/model:issued or oci://…) and standard /v2/project/model/manifests/issued URLs are also accepted. A pasted digest reference can select a pinned release; users do not need to type a fingerprint.

No models, no versions, expired sign-in, denied access and unknown publication records have explicit UI states. Use a new version name each time; the demo requires both read and push access for that version and always checks for an existing tag before uploading. Push-only accounts cannot publish through this viewer. The backend also enforces immutable tags atomically: a different manifest at an existing tag returns HTTP 409, while a retry of the same manifest preserves the original publication record. After the manifest is accepted, publication is shown as successful and the saved digest is available to reopen. Refresh versions fetches registry-recorded publication metadata separately, so a metadata outage cannot turn a successful publish into an error.

Connection and discovery boundaries

The local demo's same-origin development proxy is pinned to IFC_REGISTRY_TARGET, a loopback HTTP origin. Vite supplies this address to the UI. Pasted addresses are normalized and must identify that configured registry; loopback aliases at its port resolve to the same pinned target. Changing input cannot route the proxy to another host or port. URLs containing credentials, queries or ambiguous references are rejected before sign-in begins.

The proxy forwards /v2/, /oauth/config, /oauth/token, /oauth/revoke, Bearer-only GET /token exchanges, and the exact share API routes. Basic token requests and share credentials in query strings are not part of this flow. Only the exact token/revoke routes may pass the named oci_registry_refresh cookie; other request cookies are stripped. Response cookies must have that exact name, Path=/oauth/, HttpOnly and SameSite=Strict, with no Domain attribute. Discovery and distribution never pass cookies. Upload locations are rewritten to the viewer origin. The credential/approval page at /oauth/authorize opens directly on the configured registry origin and is never proxied under the viewer's origin. Discovery must identify that exact registry authorization endpoint, the public client ID configured by the registry, the registered viewer callback, and PKCE S256. Unexpected authorization addresses, token endpoints and upload locations are rejected. Only blob GETs may follow redirects to object storage; the browser strips the registry bearer on a cross-origin redirect and the downloaded source must still match its SHA-256 digest. Metadata requests and writes reject redirects. No browser security setting needs changing. Remote registries, arbitrary destinations, static hosting and Vite preview are outside this demo's connection scope.

Sign-in uses OAuth 2.0 Authorization Code with PKCE S256: each attempt creates a fresh random verifier and state, sends only the challenge to the registry, and redeems the returned one-time code with the matching verifier. The callback validates its exact origin/path, state and unambiguous parameters. A static callback page returns the result through the existing origin-scoped BroadcastChannel, which works with the viewer's cross-origin isolation. Sign-in times out after five minutes; closing Cloud Sources cancels an active attempt. Sign-out revokes the server session and prevents late token responses from restoring access. Remembered sign-out also clears the connected state in the viewer's other tabs; independent tab-only sessions stay separate.

Access tokens last at most 15 minutes and are renewed automatically when used. The default session keeps its rotating refresh token in tab memory and lasts up to eight hours. Closing/reopening Cloud Sources preserves that session; reloading the viewer requires sign-in again unless you chose Remember me for 30 days on the registry page.

Remembered sessions keep their refresh token only in an HttpOnly browser cookie, survive reloads and browser restarts, and are shared across tabs on the same viewer origin for an absolute 30 days. Access tokens stay in memory; refresh tokens never enter localStorage. Renewal cannot extend the original deadline or increase the originally approved grants. Web Locks serialize cookie exchanges across tabs, and concurrent model requests share one renewal within a tab. The viewer retries an authorization failure once after renewal and never retries a write after an ambiguous network error. A network failure, timeout or temporary server error during renewal keeps the session available for your next request; rejected credentials or a changed identity require sign-in again. If server sign-out fails, retry Sign out before reconnecting.

Registry-owned local accounts remain available on the registry website; CLI and ORAS retain their separate OCI login. No external identity provider is required. The viewer has no Basic-auth or password fallback.

The UI uses the Distribution catalog API at /v2/_catalog, plus OCI tag lists and manifests. Catalog listing is not a required OCI Distribution endpoint. The UI follows catalog pagination. Browser sign-in requests the session scope advertised by discovery (subsoil:session for Subsoil), captures the current account rules once, and receives a catalog-only root credential. The viewer exchanges it at /token for each concrete repository's standard OCI token; only that resource token accompanies manifest, tag, blob, and upload requests. The ordinary registry:catalog:read scope grants listing only. Added account rules/actions require another login; existing wildcard approvals include future matching repositories. Permission removals apply to existing tokens too.

Version browsing skips unsupported or malformed manifests and tags that disappear during listing. Authorization, connection and server failures remain visible. Derived releases may include larger non-IFC layers; the 512 MiB download limit applies to the selected IFC source.

Expiring shares

Choose Manage shares while signed in as an account. A share defaults to the selected immutable version with read access. Set an expiry in hours before creating the link. Live access to current/future versions and permission to publish new versions are explicit choices. The backend checks that the requested share is within the account's approved and current grants. Accounts restricted to particular tags may need to use the backend CLI/API to express a narrower live policy. Links are shown once; Revoke ends access immediately.

Paste a /share#secret=… link into Registry address to connect as a guest without an account login. The input is cleared before redemption. The secret is sent by POST, stays only in tab memory, and renews short-lived root credentials until the share's absolute deadline. Repository tokens remain separately scoped. Snapshot shares cannot read future content; an explicitly writable live share can publish new version names. Guests cannot create or administer other shares. Signing out disconnects a guest locally. An account sign-out does not revoke the independent shares it issued; use Revoke for that.

The registry's own share landing page removes the fragment before redemption. The viewer accepts links only from its configured loopback registry. HTTPS registry hosting and arbitrary remote viewer connections remain outside this local demo. For account JSON rules, TTL limits, and CLI/HTTP share operations, see the backend's authorization guide.

Titles, provenance and artifact integrity

The model and release titles come from manifest annotations or IFC filenames. New browser publications include standard org.opencontainers.image.title, .authors and .created annotations. Declared author and creation time are package claims, shown separately in Technical details.

Subsoil independently records the authenticated pushing account and server timestamp on publication. Manifest GET/HEAD responses expose optional Subsoil-Registry-Publisher and Subsoil-Registry-Pushed-At headers. The connector reads their names from the optional publication_headers token-response metadata. These are registry extensions; they do not claim the standard OCI manifest contains a trusted pusher or upload timestamp. Tag reads report that tag's original publication; digest reads report the first observed publication of those bytes in this registry. Share publications identify share:<id> and record the creator in Subsoil-Registry-Created-By. Older records with no captured provenance show Publisher not recorded and Publication time not recorded. An ORAS publication through the updated backend records its actual account just like a browser publication.

Registry publication records are stored separately and never change submitted manifest bytes or digests. The browser verifies the manifest and IFC source layer against SHA-256 before loading. New releases contain an empty OCI config and one application/x-step layer, named by org.opencontainers.image.title, with the experimental artifact type application/vnd.ifc-lite.ifc.v1. A derived release's optional single source/model.ifc can also be opened; its Parquet/GLB profile is not imported by this adapter.

Publishing uses the complete, mutation-aware STEP exporter used by Export modified IFC. It exports edits rather than re-uploading the original source buffer. The demo handles one active IFC STEP model, up to 512 MiB; IFC5, portable texture archives and incomplete exports are refused. Export coverage depends on the model and the pinned IFClite exporter.

If server sign-out fails, access is cleared from the tab and Retry sign out remains available, including after closing and reopening Cloud Sources. New sign-in is blocked until server revocation succeeds.

Focused checks

Run through the root Turbo runner, supplying the real local executables:

OCI_REGISTRY_BINARY=/absolute/path/to/subsoil \
ORAS_BINARY=/absolute/path/to/oras \
TEST_PATTERN='lib/registry/.*test|components/sources/Registry.*test' \
  pnpm test --filter=@ifc-lite/viewer --only
pnpm typecheck
pnpm lint

The separate registry-integration.yml workflow runs on registry-related pull requests or manual dispatch. It uses ubuntu-latest, no repository secrets, Subsoil commit 117c7788fbd839a855f4c324248b930e1b232f02, Rust 1.98.1, and the checksum-pinned ORAS tooling. This advisory workflow is independent of the required viewer shards and merge queue. Its setup fails if either executable is missing. Ordinary viewer tests skip the real-registry roundtrip when OCI_REGISTRY_BINARY is absent; a local run without ORAS_BINARY reports that independent retrieval was skipped. The real registry roundtrip publishes a pending wall-name edit through the viewer exporter, downloads it by digest, reparses the edit and checks the same bytes independently with ORAS. The tests cover address parsing, S256 challenge/verifier binding, callback validation, session renewal, remembered restoration, multi-tab cookie serialization, sign-out races, credential boundaries, authenticated model discovery, publisher/time metadata, actual edited IFC export, integrity, reader denials, existing-version refusal, panel-close session survival and independent ORAS retrieval. Generic file-source providers retain their existing download API; publishing is a registry-specific action within Cloud Sources.

The recorded browser walkthrough shows the password-free viewer, successful registry login, publication and reopen, with independent ORAS integrity verification.