Skip to content

Erupt Share Public Links ​

erupt-share lets a logged-in user issue a public link for one target: a form anyone holding the link may fill in (a sign-up sheet, a survey, a ticket), or a page anyone may open (a report, a dashboard, a canvas, a read-only table, a template page). Visitors need no account; the link expires, may cap visits, may ask a password and can be switched off at any time. Opening it mints an ordinary erupt session in the issuer's name, narrowed to that target — a link can never grant what its issuer does not hold.

Minimum version: 2.4.0

Setup ​

xml
<dependency>
  <groupId>xyz.erupt</groupId>
  <artifactId>erupt-share</artifactId>
  <version>${erupt.version}</version>
</dependency>

erupt-spring-boot-starter-all already includes this module, so projects on starter-all need not add it. The module depends on erupt-upms only.

Auto configuration announces the module to the frontend through registerProp("erupt-share"), and a Share Link menu appears under System Management. The frontend's /share/:code route ships with erupt-web; nothing extra needs deploying.

Share link list

System Management → Share Link: one row is one link. Type and target are fixed once saved; every other field may be changed at any time:

FieldDescriptionDefault
TitleThe name the visitor sees on the landing page—
TypePublic Form (FORM): the visitor fills in and submits the add form of a model; Public Page (MENU): the visitor opens one menu the issuer holdsFORM
TargetThe options follow the type and list only what the current user holds: FORM lists the local models with @Power(add = true) whose Add button the user holds; MENU lists every menu of theirs that opens something (button and API menus excluded)—
Expire TimeThe link stops working at this moment and no session opened from it outlives it; must be in the futureOne week ahead
Max VisitsHow many times the link may be opened; leave empty for unlimitedUnlimited
PasswordLeave empty for no password; set it again to change it. Stored only as a salted SHA-512 digest (the link code is the salt) and never sent to the browserNone
EnabledSwitching it off makes the link unavailable at once and ends its open sessionsOn

On save the server re-checks that the issuer really holds the target (a FORM model must be local, allow adding, and the issuer must hold its menu and Add button; a MENU must be in the issuer's menu tree) and refuses otherwise. Remote models (erupt-cloud nodes) cannot be shared. The code is 22 random alphanumerics, generated by the server and immutable.

Every row has two row buttons:

  • Copy Link: puts the full address (<admin app address>#/share/<code>) on the clipboard
  • Open Link: opens the link in a new tab, the way a visitor sees it

The list also shows the visit count and the last visit time. Scope: a tenant sees only its own links; inside it an administrator sees every link, other users the ones they issued. The menu allows neither import nor export.

What the Visitor Sees ​

The visitor opens #/share/<code> and lands on a page with no admin layout and no login:

  1. The landing page shows the link type, title and issuer, plus a password box when one is set. An unavailable link (unknown, disabled, expired, visits used up) shows the reason in place.
  2. Clicking "Start filling" / "Open page" trades the code (and password) for a session token. The token lives in the browser's sessionStorage, apart from the login token: opening a share link in a tab where someone is logged in never logs them out, and the share session is never used for admin pages.
  3. A FORM link renders as a standalone add form: the model name, its description, the form and a submit button — no table, no other operation. After a successful submit a "Submitted" result appears with a "Fill another" button.
  4. A MENU link renders by menu type: a template page (tpl / mtpl) opens in a full-screen iframe; a report, dashboard, canvas, table or any other menu reuses the admin's own page, hosted full screen under /share without sidebar or header.

The public form a visitor opens

When the session expires or is revoked, the API answers 401 and the page says "Share session ended, open the share link again"; reopening the link is the way back.

Security Model ​

Opening a link yields a real erupt session, so validation, DataProxy hooks, uploads and field linkage behave exactly as for a logged-in user. The session is narrowed in three ways:

Identity: the session is opened in the issuer's name, but carries no roles and is never a super admin. The identity is frozen on the link at issue time, so renaming the issuer or changing their rights later leaves existing links untouched. Every visit is written to the login log under the name issuer [share <code>].

Menus: the session holds only what the target needs — for FORM the model's menu plus its Add button, for MENU that one menu and no button. This is exactly what a user holding that menu alone could do; the frontend renders from it and @Power checks judge from it.

Routes: the module registers ShareScopeGuard through the SessionScopeGuard hook new in core 2.4.0, run by the security interceptor (and by the erupt-cloud-server interceptor as well) right after the token is verified and before the menu and model permission checks. A refused request answers 403:

Session typeAllowedRefused
FORMFor the shared model (or a sub-form vouched for through the erupt-parent header): build, add, tab add / update / delete, init value, choice / reference / tags / auto-complete / code hints, onchange, uploads, TPL fieldsTable queries, update, delete, details, export, and every endpoint of any other model
MENURoutes verified by menu or by erupt (already narrowed by a session holding one menu); login-level routes only when they declare the right they exercise with @EruptRouter(power = ...) — erupt-cube's semantic queries and dashboard detail are declared as reads, for exampleLogin-level routes that declare nothing (a password change, say), and routes behind @EruptLoginAuth

A plain login session has no scope; every guard lets it through unchanged.

Further protection:

  • Revoke: deleting a link or switching Enabled off ends every session opened from it at once
  • Session life: the smaller of erupt.share.session-minutes and the link's remaining validity, at least one minute
  • Visit cap: every successful exchange counts as one visit; the count is made in a single UPDATE statement under the cap, so two visitors racing for the last visit cannot both get it
  • Rate limit: failed exchanges (unknown code, wrong password, unavailable link) are counted per client address; once the count exceeds the limit within the window the address is refused, so neither codes nor passwords can be guessed at speed

WARNING

The code is the only secret: whoever holds the link can open it. Before sharing, make sure the target shows nothing that must stay private, and lean on the expiry, the visit cap and the password.

API ​

Before holding a session the visitor calls just two public endpoints, both under /erupt-api/share and needing no token:

EndpointDescription
GET /erupt-api/share/meta/{code}Describes the link: { title, type, issuer, requirePassword, available, reason }; available = false with a translated reason when it cannot be opened
POST /erupt-api/share/exchange/{code}Trades the code for a session, body { password } (omit when none is set); returns { token, type, target, menuType, expireMinutes } — for FORM target is the model name, for MENU target is the menu value and menuType its type. On failure an error status with the reason, which the landing page shows in place instead of a global error dialog

Everything after that goes through the ordinary erupt APIs with the minted token in the request header (the template page iframe uses the _token query parameter), and ShareScopeGuard decides what passes.

Configuration ​

properties
# Longest life of a session opened from a link, in minutes; the link's own expiry cuts it shorter
erupt.share.session-minutes=120
# Failed exchanges one client address may make within the window before it is refused
erupt.share.max-attempts=20
# Length of the attempt window, in minutes
erupt.share.attempt-window-minutes=10

Session scopes and attempt counters live in erupt's session store (memory or Redis); revoking a link scans scopes by prefix, which both stores support.

Database table ​

The module has a single table, e_share_link, extending HyperModelCreatorOnlyVo (which brings id, the creator and create_time) with a unique index on code:

ColumnTypeDescription
tenant_idVARCHAR(64)The issuer's tenant, UpmsTenant.PLATFORM for the platform; a plain column rather than @TenantId, since no tenant is known when a visitor opens the link
codeVARCHAR(32)The link code, 22 random alphanumerics, unique
titleVARCHAR(200)Title
typeVARCHAR(10)FORM / MENU
targetVARCHAR(100)Model name for FORM, menu code for MENU
expire_timeDATETIMEExpiry
max_visitsINTVisit cap, null for unlimited
visit_countINTVisits so far
last_visit_timeDATETIMELast visit
password_hashVARCHAR(200)Salted SHA-512 digest of the password, null when none
enabledBIT(1)Enabled flag
issuer_id / issuer_account / issuer_nameBIGINT / VARCHAR(100) / VARCHAR(100)The issuer's identity frozen at issue time, in whose name the visitor's session is opened

Projects with JPA schema generation enabled get the table on upgrade; projects that maintain their schema by hand should create it from the table above.

Contributors

The avatar of contributor named as YuePeng YuePeng

Changelog

Released under the Apache-2.0 License.