[delchev]

What

share: on an entity declares that the issued copy of its records may be opened by a reader without an account, through a link a user creates on the record.

- name: SalesInvoice
  share:
    when: "status == ISSUED"     # required
    copy: SalesInvoiceCopy       # required: a function: Snapshot child
    roles: [SalesInvoiceShare]   # required key; [] admits nobody
    expiresAfterDays: 0          # optional, 0 = permanent

No block, no link: all generated share code sits under #if($share), and no setting makes an undeclared entity shareable.

How

• Parser (IntentParser.validateShare) refuses the block without when:, without a copy: that is a Snapshot composition child of the same printable document, without roles:, with a role permissions does not declare, with expiresAfterDays outside 0..3650, and on a personal entity (own personal: true relation or a composition ancestor's).
• New module engine-share
  • Links live per tenant in DIRIGIBLE_SHARE_LINKS; each open is a row in DIRIGIBLE_SHARE_LINK_OPENS (time, link, remote address, user agent).
  • The token is 256 CSPRNG bits, base64url, stored only as SHA-256 and returned once. It is unrelated to the record's uuid.
  • GET /public/share/{token} serves the one stored file fixed when the link was created. Unknown, expired, revoked, other-tenant and file-gone tokens all get the same empty 404. It reads and creates no session.
  • Throttling is in memory, per address and per link, with a back-off after repeated misses (429 + Retry-After).
  • Nothing is cached, so a revoke takes effect on the next request on every node.
• Leaving the when: state (guardrail 10) is checked at open time. The generated repository implements ShareSubject, and the public route asks it on every open. A record found outside the state has its link revoked for good (revokedBy: system). I chose this over hooking each repository write path, of which there are five, some generated conditionally.
• Generated code: GET|POST /{id}/share-links and DELETE /{id}/share-links/{linkId} on the entity's controller, gated by the declared roles only, plus a "Share links" section on the form and document record pages (one shared shareLinksPanel.js). Not generated on the my/partner surfaces.
• Tenant settings: DIRIGIBLE_DOCUMENTS_SHARE_ENABLED (off switch) and DIRIGIBLE_DOCUMENTS_SHARE_MAX_EXPIRY_DAYS (only shortens). Instance settings: DIRIGIBLE_DOCUMENTS_SHARE_RATE_LIMIT_PER_MINUTE, DIRIGIBLE_DOCUMENTS_SHARE_MISS_LIMIT.
• TOKEN_GROUPS: one host serves every tenant and an anonymous request has no tenant, so there the token is <tenantId>.<secret> and the route switches into that tenant for the lookup. Under SUBDOMAIN the host decides, and another tenant's token is simply not in the table.

Deviations from the issue

• {shareUrl} in notify bodies is not in this PR. A send bound to the issuing transition usually runs before the copy is minted, so it needs its own ordering and failure contract. Filed as intent: {shareUrl} in a notify body - mail a share link instead of (or next to) the attachment (follow-up of #8613) #8616.
• Audit is the link row (created/revoked by and at, open count, last opened), the opens table and INFO log lines. The activity stream ([Activity] Activity stream - audit trail + usage telemetry, optional via DIRIGIBLE_ACTIVITY_STREAM_ENABLED + DIRIGIBLE_ACTIVITY_* (umbrella) #7472) does not exist yet.
• Only a PDF is served inline; any other content type is sent as a download. The generated code only ever links Snapshot PDFs; this covers custom code calling the SDK facade with another file.
• A link serves the copy that was newest when it was created. A later amendment's copy needs a new link.

Verified

• ShareIntentTest (14): the parse refusals for guardrails 3, 4 and 11.
• ShareLinkServiceTest (15, real H2 table) and ShareRateLimiterTest (4).
• IntentShareLinkIT against the published application, over HTTP: a draft is refused; a role-less user gets 403 on all three endpoints; a role holder creates a link; an anonymous open returns the copy's bytes with no Set-Cookie; the record's uuid and the link id as token give 404; the token on another tenant's host gives 404; an entity without share: has no route; revoke, expiry and void each give 404; repeated misses give 429.
• IntentEmissionCoverageIT with share: added to its fixture (generated repository, controller, page, and none of it on an undeclared entity).
• Also green locally: IntentEngineIT, ModelGenerationIT, EndpointAuthorizationIT, HarmoniaContractIT, HarmoniaRecordActionsIT, TenantConfigurationIT.
• Unit suites of commons-config, core-configurations, engine-share, engine-intent, ide-template, api-modules-java; formatter:validate on the whole reactor with the cache wiped; the release javadoc build of the changed modules.

Not verified

• The Share links section was not opened in a browser. Its markup is asserted in generated output and passes HarmoniaContractIT, but no Selenide test clicks through it.
• All ITs ran on H2 only, not PostgreSQL.
• The TOKEN_GROUPS path is covered by the unit test only; no Keycloak IT.

Docs: IntentFile/intent-specification#238, IntentFile/intentfile.github.io#85, dirigible-io/dirigible-io.github.io#292 (merge after this one).

Fixes #8613

🤖 Generated with Claude Code