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¶
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.
- Open File → Cloud Sources, expand Model registry, and paste
http://localhost:5000into 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. - 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.
- Select a wall, open Author → Model, and edit Name in the Model inspector. Press Tab to apply the edit.
- Reopen Cloud Sources → Model registry. The connection remains signed in. Enter a fresh version name and click Publish edited model.
- 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.
- 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.