SHEF NuQloud Custom Account Creation

An isolated Nextcloud app for Sacred Honor Educational Fellowship onboarding. It owns shef_fellowship and the development-only shef_fellowship_dev invitations; standard NuQloud invitations remain on the existing qortal_integration page.

Flow

1. The fellowship application records agreement acceptance and calls this app's server-to-server invite API.
2. This app creates a typed broker invite, records the agreement version and invite-token hash, and emails the private link.
3. The private link starts the selected SHEF application's /auth/login route with the invitation token.
4. SHEF creates the normal OIDC state, nonce, and PKCE transaction, then asks the broker to authorize its registered client.
5. The broker detects the typed invite and returns to this branded page to collect account details.
6. The broker returns the authorization code to SHEF's /auth/callback; SHEF validates it and creates its own authenticated session.

The fellowship application's API token and the broker internal token must stay on servers only. Never send either token to browser code.

Manual installation

Copy this repository into the NuQloud custom-apps directory as shef_nuqloud_onboarding, then enable it with OCC. Configure values with config:app:set; do not commit credentials.

Required app settings:

• broker_base_url: broker URL reachable from Nextcloud, for example http://broker:3000.
• broker_issuer_url: public HTTPS broker issuer URL used by the browser.
• broker_internal_api_token: existing broker internal API token.
• client_api_token: a separate high-entropy token held only by the fellowship application's backend.
• agreement_version: the agreement identifier required by the API, default v1.
• app_login_url: the exact HTTPS SHEF staging login URL, for example https://shef-staging.winnr.dev/auth/login.

Optional settings: client_name, invite_ttl_hours (1–336), and completion_url (the legacy authenticated completion-page destination). New SHEF invitations return directly to the SHEF OIDC callback and do not use completion_url.

For development-only invitations, set a separate dev_client_api_token. It always starts the fixed local route http://localhost:3000/auth/login; it does not accept a caller-supplied URL. Only use this token from a developer's local backend and only open its emailed invitation on that same developer machine.

The broker must be configured with this presentation route:

{"shef_fellowship":"https://cloud.example/apps/shef_nuqloud_onboarding/invite","shef_fellowship_dev":"https://cloud.example/apps/shef_nuqloud_onboarding/invite"}

Set it through OIDC_CUSTOM_INVITE_PRESENTATION_URLS. Also bind each invite type to its registered SHEF OIDC client through OIDC_CUSTOM_INVITE_ALLOWED_CLIENT_IDS, for example:

{"shef_fellowship":["shef-web-staging"],"shef_fellowship_dev":["shef-web-dev"]}

Without these mappings, the custom invitation cannot proceed to the branded account-creation form or is not restricted to its intended SHEF client.

Invite API

POST /apps/shef_nuqloud_onboarding/api/invites

Required header: X-Shef-Client-Token. The normal staging token creates shef_fellowship invitations; the separate development token creates shef_fellowship_dev invitations.

JSON body:

{
  "email": "member@example.org",
  "agreementAccepted": true,
  "agreementVersion": "v1"
}

The endpoint returns 202 without exposing the invitation token or link.

Admin resend

On cloud instances with this app enabled, the NuQloud dashboard invitation table labels the staging and development SHEF rows separately. For an active row, a Nextcloud administrator or configured NQ_Admin delegated administrator can use Send E-Mail to resend the existing private invitation. The dashboard intentionally does not expose a copyable link for SHEF invitations; standard invitations retain their existing link and email actions.

The resend endpoint is session-authenticated and CSRF-protected. It only accepts active SHEF invitation types and sends the stored recipient email; it never returns the invitation token or link.