@jahia/agentic 0.0.0

package/dist/copilot/.agents/skills/jahia-dev-apis/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: jahia-dev-apis
+description: >
+  Jahia 8.2 developer API reference covering GraphQL, JCR Java API, RESTful JCR access,
+  OAuth/SAML authentication, personal API tokens, HTML filtering, and Content Security Policy.
+
+  Trigger this skill when the user is:
+  - Working with the Jahia GraphQL API (queries, mutations, schema extensions, Apollo client)
+  - Using the JCR Java API to read/write content nodes
+  - Accessing the RESTful JCR API or building JAX-RS endpoints
+  - Setting up OAuth 2.0 (social login) or building a custom OAuth connector
+  - Configuring SAML 2.0 authentication
+  - Using the UPA (username/password + MFA) authentication module
+  - Creating or using personal API tokens
+  - Configuring HTML filtering (XSS protection) for content properties
+  - Setting up a Content Security Policy (CSP) for a Jahia site
+  - Configuring the security filter/service (API authorization, CORS, scopes)
+  - Asking which Jahia API to use (GraphQL vs REST vs Actions)
+allowed-tools: Read
+---
+
+# Jahia 8.2 Developer APIs
+
+This skill covers all developer-facing APIs and security configuration in Jahia 8.2.
+
+## Reference files
+
+| File | When to use |
+|------|-------------|
+| `references/graphql.md` | GraphQL endpoint URL, JCR queries/mutations, schema extension (SDL + Java), connection/pagination pattern, Apollo client setup, CORS and auth config |
+| `references/jcr-api.md` | Java JCR Session API (read/write nodes), auto-splitting, property interceptors, RESTful JCR access (REST endpoints, HAL+JSON), JAX-RS endpoint registration, Actions (legacy) |
+| `references/authentication.md` | OAuth 2.0 social login modules, building a custom OAuth connector, SAML 2.0 setup, UPA (username/password + MFA) module, personal API tokens (create/use/manage via Groovy) |
+| `references/security.md` | Security filter/service (scope-based authorization config), HTML filtering v2 (YAML config, strategies, workspace rules), Content Security Policy setup, JahiaUserManagerService |
+
+## Quick API overview
+
+| API | Endpoint / Access | Primary use case |
+|-----|-------------------|------------------|
+| GraphQL | `POST /modules/graphql` | Client-side apps, SPA; flexible queries, mutations, JCR node access, custom schema extension |
+| RESTful JCR | `GET/PUT/DELETE /modules/api/jcr/v1/{workspace}/{lang}/nodes/{id}` | CRUD on JCR nodes via HTTP; useful for automation scripts and server-to-server calls |
+| JAX-RS (custom REST) | Registered under `/modules/{alias}` via OSGi bundle directives | Custom REST endpoints packaged as Jahia modules |
+| JCR Java API | `JCRTemplate.getInstance().doExecuteWithSystemSession(...)` | Server-side Java code; direct node manipulation inside modules |
+| Actions | `POST /{path}.{actionName}.do` | Legacy: simple isolated server-side operations triggered from forms or rules |
+| Personal API tokens | `Authorization: APIToken <token>` header | Authenticate API calls without credentials; scoped access |
+| JWT tokens | `Authorization: Bearer <token>` header | Deprecated — use personal API tokens instead |
+
+## Key Jahia-specific concepts
+
+- **Workspaces**: `EDIT` (default) and `LIVE`. GraphQL queries default to `EDIT`; specify `jcr(workspace: LIVE)` for published content.
+- **Security filter**: All APIs (GraphQL, REST, views) are closed by default. Access is granted via scope-based config files in `karaf/etc` with pattern `org.jahia.bundles.api.authorization-*.yml`.
+- **Internationalization**: JCR sessions are opened in one language; GraphQL can query multiple languages in one call using `language:` arguments on individual fields.
+- **Session save**: Every JCR write must end with `session.save()`. In GraphQL mutations, save is automatic at the end of each `mutation { jcr }` block.

package/dist/copilot/.agents/skills/jahia-dev-apis/references/authentication.md

@@ -0,0 +1,484 @@
+# Authentication Reference
+
+Covers personal API tokens, OAuth 2.0 social login, SAML 2.0, and the UPA (username/password + MFA) module.
+
+## Table of Contents
+
+- [Personal API Tokens](#personal-api-tokens)
+  - [Module installation](#module-installation)
+  - [Creating a token via admin UI](#creating-a-token-via-admin-ui)
+  - [Using tokens in API calls](#using-tokens-in-api-calls)
+  - [Managing tokens](#managing-tokens)
+  - [Managing tokens via GraphQL](#managing-tokens-via-graphql)
+  - [Managing tokens via filesystem (Groovy)](#managing-tokens-via-filesystem-groovy)
+- [OAuth 2.0 — Social Login](#oauth-20--social-login)
+  - [Available connectors](#available-connectors)
+  - [Required modules](#required-modules)
+  - [Configuring a social connector](#configuring-a-social-connector)
+  - [Mapping user fields](#mapping-user-fields)
+  - [Adding social login buttons to pages](#adding-social-login-buttons-to-pages)
+  - [Building a custom OAuth connector](#building-a-custom-oauth-connector)
+- [SAML 2.0](#saml-20)
+  - [Module installation](#module-installation-1)
+  - [Creating a keystore](#creating-a-keystore)
+  - [Configuring SAML in Site Settings](#configuring-saml-in-site-settings)
+  - [Configuration file example](#configuration-file-example)
+  - [Mapping users from IdP](#mapping-users-from-idp)
+  - [Triggering SAML login](#triggering-saml-login)
+  - [Private pages and SAML authentication](#private-pages-and-saml-authentication)
+- [UPA — User Password Authentication Module](#upa--user-password-authentication-module)
+  - [What it adds over default auth](#what-it-adds-over-default-auth)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+  - [Setup: login URL provider](#setup-login-url-provider)
+  - [Authentication flow](#authentication-flow)
+  - [Customization](#customization)
+  - [Known limitations](#known-limitations)
+
+---
+
+## Personal API Tokens
+
+Module ID: `personal-api-tokens`. Compatible with Jahia 8.0.1+. Tokens are stored in the JCR and persist across upgrades.
+
+**Key concept:** A token is tied to its creator's account and inherits that user's permissions. Create one token per external service — if a token is compromised, revoke only that token without affecting others.
+
+### Module installation
+
+Install via **Jahia Administration > Modules and Extensions > Modules**. Requires the module to be deployed on the server (not per site).
+
+### Creating a token via admin UI
+
+1. Navigate to **Dashboard > My API tokens**.
+2. Click **Create Token**.
+3. Provide a **Name** (unique per user) and an optional **Expiration date**.
+4. Click **Create**. The token string is shown **once only** — copy it immediately.
+
+Access to this page requires the **"Personal api tokens"** server role permission. "Live role" or "Edit role" is not sufficient.
+
+### Using tokens in API calls
+
+Pass the token in the `Authorization` header prefixed with `APIToken`:
+
+```
+Authorization: APIToken <your-token-value>
+```
+
+**cURL example:**
+
+```bash
+curl -H "Authorization: APIToken XXXXXXXXXX" https://JAHIA_URL/modules/healthcheck
+```
+
+**Apollo Client (TypeScript) example:**
+
+```typescript
+export const apolloClient = (token: string): ApolloClient => {
+  return new ApolloClient({
+    link: new HttpLink({
+      uri: `JAHIA_URL/modules/graphql`,
+      headers: {
+        authorization: `APIToken ${token}`
+      }
+    }),
+    cache: new InMemoryCache(),
+    defaultOptions: {
+      query: { fetchPolicy: 'no-cache' }
+    }
+  });
+};
+```
+
+### Managing tokens
+
+From **Dashboard > My API tokens**, you can view token name, access key, expiration date, and status. Actions: **Delete**, **Activate**, **Disable**.
+
+Admins can manage other users' tokens at **Administration > Users and Roles > User API tokens** (requires the "Admin personal api tokens" server administration permission). Admins can disable/delete but cannot create tokens for other users.
+
+### Managing tokens via GraphQL
+
+Entry point: `admin.personalAPITokens`. Additional operations beyond the UI:
+
+- `verifyToken` — check if a token is valid
+- Update a token's name or expiry date
+
+### Managing tokens via filesystem (Groovy)
+
+Useful for automating token creation on first Jahia startup. Place Groovy scripts in `digital-factory-data/patches/groovy/`. Use the CLI tool to generate valid token strings:
+
+```bash
+git clone git@github.com:Jahia/personal-api-token
+cd personal-api-token && mvn clean install
+cd target && java -jar personal-api-tokens-1.6.0-cli.jar
+# Output: {"token": "b765L5rY...", "key": "6fbeb92f-..."}
+```
+
+**Create a token via Groovy:**
+
+```groovy
+setResult("remove");
+org.jahia.services.content.JCRTemplate.getInstance().doExecuteWithSystemSession({ session ->
+    org.jahia.osgi.BundleUtils.getOsgiService("org.jahia.modules.apitokens.TokenService")
+        .tokenBuilder("/users/root", "test-token12345", session)
+        .setToken("kgHNm05iQV61I+GY3X5HVr13i866HAAsyou8G+eGubk=")
+        .setActive(true)
+        .setExpirationDate(new org.joda.time.DateTime('2021-12-31').toCalendar(Locale.getDefault()))
+        .create()
+    session.save();
+})
+```
+
+**Delete a token via Groovy:**
+
+```groovy
+setResult("remove");
+org.jahia.services.content.JCRTemplate.getInstance().doExecuteWithSystemSession({ session ->
+    org.jahia.osgi.BundleUtils.getOsgiService("org.jahia.modules.apitokens.TokenService")
+        .deleteToken("9201cd9b-4e62-415e-b523-e198dd7e4756", session)
+    session.save();
+})
+```
+
+**Update a token via Groovy:**
+
+```groovy
+setResult("remove");
+org.jahia.services.content.JCRTemplate.getInstance().doExecuteWithSystemSession({ session ->
+    def service = org.jahia.osgi.BundleUtils.getOsgiService("org.jahia.modules.apitokens.TokenService")
+    def tokenDetails = service.getTokenDetails("9201cd9b-4e62-415e-b523-e198dd7e4756", session)
+    tokenDetails.setActive(false)
+    service.updateToken(tokenDetails, session)
+    session.save();
+})
+```
+
+`setResult("remove")` causes the Groovy script file to be deleted after execution.
+
+---
+
+## OAuth 2.0 — Social Login
+
+### Available connectors
+
+The Jahia OAuth module (compatible with Jahia 8.0.1+) bundles connectors for:
+
+- Google
+- Facebook
+- LinkedIn
+- GitHub
+- FranceConnect
+
+No code is required to use the built-in connectors; login buttons are added via drag-and-drop.
+
+### Required modules
+
+| Module | Purpose |
+|--------|---------|
+| Jahia Authentication | Backbone SSO framework |
+| Jahia OAuth | OAuth connectors (Google, Facebook, etc.) |
+| JCR Authentication Provider | Maps social profile attributes to Jahia user attributes |
+| jExperience Auth data mapper | (Optional) Maps attributes to jExperience visitor profiles for personalization |
+
+Install all required modules via **Jahia Administration > Modules and Extensions > Modules** before configuring.
+
+### Configuring a social connector
+
+1. Navigate to **Administration > Sites > Jahia Authentication**.
+2. Expand the connector to configure (e.g., **Google Connector**).
+3. Toggle **Activate**.
+4. Fill in:
+   - **ID Client** — your OAuth application's client ID
+   - **Secret client** — your OAuth application's secret
+   - **Scope** — data to request from users (e.g., `profile email` for GitHub, `public_profile` for Facebook, `r_emailaddress r_liteprofile` for LinkedIn)
+   - **Callback URL** — where users are redirected after login. Must end with the connector-specific suffix, e.g., `.googleOAuthCallbackAction.do`. Example: `http://mysite.com/sites/digitall/home.googleOAuthCallbackAction.do`
+5. Click **Save**.
+
+After saving, the **Actions** button becomes available for user field mapping.
+
+**Creating OAuth applications** (external provider consoles):
+
+- Google: https://console.developers.google.com/apis/credentials/oauthclient
+- Facebook: https://developers.facebook.com/apps/
+- LinkedIn: https://www.linkedin.com/developers/
+- GitHub: https://github.com/settings/developers
+- FranceConnect: https://partenaires.franceconnect.gouv.fr/fcp/fournisseur-identite
+
+### Mapping user fields
+
+After configuring a connector, map the social login fields to Jahia user fields:
+
+1. On the connector settings page, click **Actions**.
+2. Expand the **JCR OAuth provider** section and toggle **Activate**.
+3. In **Field from connector**, select social fields (e.g., First name, Last name, Google ID).
+4. In **Field from provider**, select Jahia fields (e.g., First name, Last name, Login username mandatory).
+5. Click **Save**.
+
+### Adding social login buttons to pages
+
+Add social login buttons like any Jahia component — find them under **Jahia OAuth button connector** in the **Select Content Type** dialog.
+
+When Jahia OAuth is enabled, an **Authentication Results** page is created at `sites/_your-project_/oauth-result`. This page must be published.
+
+### Building a custom OAuth connector
+
+Requirements: OAuth 2.x protocol, knowledge of Jahia module development.
+
+**Steps:**
+
+1. Create a Jahia module.
+
+2. Add dependencies to `pom.xml`:
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.jahia.modules</groupId>
+        <artifactId>jahia-oauth</artifactId>
+        <version>3.0.0</version>
+        <scope>provided</scope>
+    </dependency>
+    <dependency>
+        <groupId>org.jahia.modules</groupId>
+        <artifactId>jahia-authentication</artifactId>
+        <version>1.0.0</version>
+        <scope>provided</scope>
+    </dependency>
+</dependencies>
+```
+
+3. Add node types to `definitions.cnd`:
+
+```
+[joant:myConnectorOAuthView] > jnt:content, jmix:authConnectorSettingView
+[joant:myConnectorButton] > jnt:content, joamix:oauthButtonConnector
+```
+
+4. Register the OSGi service in your blueprint XML:
+
+```xml
+<osgi:reference id="jahiaOAuthService"
+    interface="org.jahia.modules.jahiaoauth.service.JahiaOAuthService"
+    availability="mandatory"/>
+
+<osgi:service ref="MyConnectorImpl"
+    interface="org.jahia.modules.jahiaoauth.service.ConnectorService">
+    <osgi:service-properties>
+        <entry key="connectorServiceName" value="MyConnectorApi"/>
+    </osgi:service-properties>
+</osgi:service>
+```
+
+The `connectorServiceName` must be consistent between the blueprint, the Spring file in Jahia OAuth module, and any JavaScript code in your module.
+
+5. Create views for `joant:myConnectorOAuthView` (settings UI) and `joant:myConnectorButton` (login button).
+
+**Action modules** execute logic after authentication (e.g., provision users). Two types:
+
+- **Provider** — performs the login/connection
+- **Data mapper** — stores user data (e.g., to jExperience profiles)
+
+Implement `org.jahia.modules.jahiaauth.service.Mapper` for data mapper action modules.
+
+---
+
+## SAML 2.0
+
+### Module installation
+
+Deploy and install these three modules:
+
+1. [SAML2 Authentication Valve](https://store.jahia.com/contents/modules-repository/org/jahia/modules/saml-authentication-valve.html)
+2. [Jahia Authentication](https://store.jahia.com/contents/modules-repository/org/jahia/modules/jahia-authentication.html)
+3. [JCR Authentication Provider](https://store.jahia.com/contents/modules-repository/org/jahia/modules/jcr-auth-provider.html)
+
+### Creating a keystore
+
+```bash
+keytool -genkeypair \
+    -alias jahiakeystorealias \
+    -keypass changeit \
+    -keystore sp.jks \
+    -storepass changeit \
+    -keyalg RSA \
+    -keysize 2048 \
+    -validity 3650
+```
+
+When prompted "What is your first and last name?", enter your Jahia site domain name (must match `jahia.server.name`).
+
+### Configuring SAML in Site Settings
+
+1. Navigate to **Administration > Sites > Jahia Authentication** and expand **SAML2 Settings**.
+2. Toggle **Activate**.
+3. Upload the **Identity Provider Metadata** XML file (from your IdP, e.g., Shibboleth, Google).
+4. Fill in:
+   - **Relying Party Identifier** — your SP identifier sent to the IdP
+   - **Server Location** — public URL of your Jahia site (e.g., `http://localhost:8080`)
+   - Keystore values (or leave keystore empty to auto-generate one using hostname as CN)
+   - **Incoming Target URL** — where IdP returns SAML response (default: `/home.callback.saml`)
+   - **Redirect after successful login** — Jahia relative URL (e.g., `/home.html`)
+   - **Maximum authentication lifetime** — max age of IdP session before re-authentication
+5. Select optional flags: Force authentication, Passive authentication, Sign authentication request, Requires signed assertions.
+6. Select **Binding type** (e.g., `HTTP-POST`).
+7. Click **Save**.
+
+After saving, **Open Service Provider Metadata** becomes available for downloading SP metadata to share with the IdP.
+
+### Configuration file example
+
+SAML config is stored per-site in `karaf/etc`:
+
+```properties
+# SAML Configuration file - autogenerated
+siteKey = digitall
+enabled = true
+identityProviderMetadata = ...
+relyingPartyIdentifier = test-local
+serverLocation = http://localhost:8080
+keyStore = ...
+keyStoreAlias = saml2clientconfiguration
+keyStorePass = changeit
+privateKeyPass = changeit
+incomingTargetUrl = /home.callback.saml
+postLoginPath = /home.html
+maximumAuthenticationLifetime = 86400
+forceAuth = false
+passive = false
+requireSignedAssertions = false
+signAuthnRequest = true
+bindingType = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
+keyStoreType = PKCS12
+mapperName = jcrOAuthProvider
+```
+
+### Mapping users from IdP
+
+1. On the **SAML2 Settings** page, click **Mappers**.
+2. Expand and activate the **JCR Authentication Provider** section.
+3. In **Field from connector**, select IdP fields (e.g., Login).
+4. In **Field from provider**, select Jahia fields (e.g., Login username mandatory).
+5. Click **Save**.
+
+### Triggering SAML login
+
+Users are redirected to the IdP by calling `*.connect.saml?siteKey={sitekey}`:
+
+```
+http://localhost/sites/mySite/home.connect.saml?siteKey=mySite
+```
+
+You can also use a form component (included with the module) or embed the redirect in a JSP/template.
+
+**Redirect to a specific page after login** using the `redirect` query param:
+
+```
+/sites/mySite/home.connect.saml?siteKey=mySite&redirect=/sites/mySite/about-us.html
+```
+
+The `siteKey` param is required unless the server name is mapped to a site in Jahia (even then, using `siteKey` is recommended).
+
+**JSP form example:**
+
+```jsp
+<c:if test="${not renderContext.loggedIn}">
+    <form action="${renderContext.mainResource.node.name}.connect.saml" method="GET">
+        <input type="hidden" name="siteKey" value="${renderContext.site.siteKey}"/>
+        <input type="hidden" name="redirect"
+               value="${renderContext.mainResource.nodePath}.${renderContext.mainResource.templateType}"/>
+        <input type="submit" value="${currentNode.displayableName}">
+    </form>
+</c:if>
+```
+
+Redirect URLs are filtered: only local URLs (no hostname) are accepted to prevent XSS.
+
+### Private pages and SAML authentication
+
+By default Jahia returns HTTP 404 for private pages to hide their existence. To redirect unauthenticated users to the SAML IdP instead, configure `jahia.properties`:
+
+```properties
+# authorizationError returns 401 for guests, 403 for authenticated users without permission
+protectedResourceAccessStrategy=authorizationError
+```
+
+Then customize the 401 error page to include a link to `*.connect.saml`. For sites where the site root itself is private:
+
+```bash
+cp error_401.jsp <tomcat_home>/webapps/ROOT/errors/sites/<mySite>/error_401.jsp
+```
+
+**Common SAML authentication error causes:**
+
+- Missing or wrong `siteKey` query param
+- Missing or unreadable SAML configuration file for the site
+- Wrong keystore or certificate configuration
+- Mismatched Relying Party Identifier
+
+Clients always receive HTTP 400 on authentication failure — check server logs for the root cause.
+
+---
+
+## UPA — User Password Authentication Module
+
+### What it adds over default auth
+
+The UPA module provides a custom username/password login flow with optional multi-factor authentication (MFA via email code). It replaces the default Jahia login page with a configurable React-based UI. It is not a full IdP replacement — prefer SAML or OpenID for enterprise SSO.
+
+**Important:** Once the API module is enabled, it overrides the default login URL for **all sites** on the platform. The legacy `/cms/login` endpoint remains active and must be blocked at the reverse proxy for full security.
+
+### Prerequisites
+
+- Jahia 8.2.3 or higher
+- GraphQL DXM Provider module (included in Jahia core)
+- For MFA email code: working SMTP server and users must have `j:email` set
+- For clusters: sticky sessions or distributed sessions required
+
+### Installation
+
+Two modules from the [Jahia Store](https://store.jahia.com/):
+
+1. **API module** (`user-password-authentication-api-X.Y.Z.jar`) — provides GraphQL APIs; install and enable platform-wide
+2. **UI module** (`user-password-authentication-ui-X.Y.Z.tgz`) — React-based login form; install and enable per site
+
+### Setup: login URL provider
+
+Configure where users are redirected when accessing protected resources (choose one option):
+
+**Option A (recommended):** Set `loginUrl` in OSGi console (`org.jahia.modules.upa` configuration):
+- Navigate to **Tools > OSGi Console > OSGi > Configuration**
+- Set `loginUrl` to the login page URL (e.g., `/sites/mySite/login.html`)
+- The URL must include the site key for email template resolution
+
+**Option B:** Install the community *Site Settings - Customize Error Pages* module.
+
+**Option C:** Implement a custom `LoginUrlProvider` interface.
+
+After configuring the URL provider, create the login page in Page Builder, add the **UPA Authentication** component (`upaui:authentication`), publish the page, and verify it is accessible without authentication.
+
+### Authentication flow
+
+1. User accesses protected content → redirected to login page
+2. User enters username/email and password
+3. If MFA is enabled: user receives a code by email and enters it in a verification form
+4. On success: user is redirected to the originally requested resource
+
+MFA follows a two-step model per factor:
+- **Prepare** — generates and sends the challenge (e.g., email code)
+- **Verify** — validates the user's response
+
+### Customization
+
+**Custom MFA email template:** Create a view with selector `mailCodeView` at higher priority for `upa:mfaMailCode` node type. Use `{{CODE}}` placeholder for the verification code. Use inline CSS (email client compatibility).
+
+**Custom UI:** Only the API module is strictly required. Copy the [UI module source](https://github.com/Jahia/user-password-authentication/tree/main/ui/) and customize it. The GraphQL APIs are available at `/modules/graphql-dxm-provider/tools/graphql-workspace.jsp`.
+
+**Custom MFA factor:** Implement the `MfaFactorProvider` interface (experimental, subject to change).
+
+### Known limitations
+
+| Limitation | Detail |
+|-----------|--------|
+| Global login URL | `loginUrl` applies platform-wide, across all sites |
+| Cluster lockout | Max failed attempts per cluster node: `((T-1) × N) + 1` where T = tries configured, N = node count |
+| Multiple providers | Only one custom `LoginUrlProvider` can be active at a time |
+| Legacy endpoint | `/cms/login` bypasses UPA; must be blocked at the proxy level |