@tideorg/mcp 1.4.0

package/canon/tidecloak-endpoints.md

@@ -0,0 +1,294 @@
+# TideCloak Extension Endpoints - Canon
+
+Complete reference of all REST endpoints added by TideCloak extensions. These are in addition to standard Keycloak endpoints.
+
+Admin endpoints require a Bearer token with `manage-realm` or `manage-users` permission.
+Public endpoints require no authentication.
+
+---
+
+## URL Patterns
+
+- Admin API: `/admin/realms/{realm}/{provider-id}/{path}`
+- Public realm: `/realms/{realm}/{provider-id}/{path}`
+
+---
+
+## App Developer Endpoints
+
+These are the endpoints app developers interact with most frequently.
+
+### Adapter JSON Export
+
+```
+GET /admin/realms/{realm}/vendorResources/get-installations-provider
+  ?clientId={uuid}&providerId=keycloak-oidc-keycloak-json
+```
+
+Returns the client adapter JSON with Tide-specific fields (`jwk`, `vendorId`, `homeOrkUrl`, `client-origin-auth-*`). The `jwk` field is only present when IGA is enabled. Save as `data/tidecloak.json`.
+
+### Public Tide Config
+
+```
+GET /realms/{realm}/public/get-tide-config?clientId={clientId}
+```
+
+Public endpoint. Returns `vendorId`, `homeOrkUrl`, client auth origins, and branding URLs for a client. No auth required.
+
+### Admin Policy (for E2EE)
+
+```
+GET /realms/{realm}/tide-policy-resources/admin-policy
+```
+
+Public endpoint. Returns the base64-encoded admin policy needed for policy-based encryption operations. Also available as `/admin-policy/bytes` (raw) and `/admin-policy/display` (human-readable).
+
+### Role Policy
+
+```
+GET /realms/{realm}/tide-policy-resources/policy?roleId={id}&clientId={id}
+```
+
+Public endpoint. Returns the Midgard policy for a specific role on a client.
+
+### Vouchers
+
+```
+POST /realms/{realm}/tidevouchers/fromUserSession?sessionId={sid}
+```
+
+Gets vouchers for a user session. Role-based: `signin`/`updateaccount` always allowed; `vendorsign` requires `_tide_*` or authorizer role; `vendordecrypt` requires `_tide_*.selfdecrypt` role. The SDK constructs this URL internally.
+
+```
+POST /realms/{realm}/tidevouchers/fromAuthSession?sessionId={sid}&tabId={tab}&clientId={id}
+```
+
+Gets vouchers during authentication flow (login).
+
+### DPoP Auth Page
+
+```
+GET /realms/{realm}/tide-idp-resources/clientIframe/iss/{iss}/aud/{aud}/tide_dpop_auth.html
+```
+
+Serves the DPoP authentication iframe HTML. `iss` and `aud` are hex-encoded. The SDK uses this internally.
+
+### Token Exchange (Delegation)
+
+```
+POST /realms/{realm}/protocol/openid-connect/token
+```
+
+Standard OIDC token endpoint used for delegation token exchange:
+- `grant_type=urn:ietf:params:oauth:grant-type:token-exchange`
+- `subject_token=<user access token>`
+- `actor_token=<browser-signed delegation request>`
+- `dpop_approval=<session key approval>`
+- `DPoP` header: server's DPoP proof
+
+See `canon/delegation.md` for full flow.
+
+---
+
+## Bootstrap Endpoints
+
+Used during realm initialization. Typically called by the init script, not by app code.
+
+### Realm Setup
+
+```
+POST /admin/realms/{realm}/vendorResources/setUpTideRealm
+Content-Type: application/x-www-form-urlencoded
+Body: email=admin@yourorg.com
+```
+
+Full Tide realm setup: creates IDP, key provider, gets free-tier license. `isRagnarokEnabled` optional (default true). Content-Type MUST be form-encoded, not JSON.
+
+### Enable IGA
+
+```
+POST /admin/realms/{realm}/tide-admin/toggle-iga
+Content-Type: application/x-www-form-urlencoded
+Body: isIGAEnabled=true
+```
+
+Enables IGA governance for the realm. Sets EdDSA signature algorithm, configures Tide protocol mappers.
+
+### Sign IDP Settings
+
+```
+POST /admin/realms/{realm}/vendorResources/sign-idp-settings
+```
+
+Signs all Tide IDP settings with the VRK. Required after any IDP config change (logo, background, admin domain, client origins). Without this, the ORK enclave rejects settings as unsigned.
+
+### Admin Invite Link
+
+```
+POST /admin/realms/{realm}/tideAdminResources/get-required-action-link
+  ?userId={id}&redirectUri={uri}&clientId={id}&lifespan=43200
+Body: ["link-tide-account-action"]
+```
+
+Generates a link for the admin user to link their Tide account. Time-limited (default 12 hours).
+
+---
+
+## IGA Change-Set Endpoints
+
+Used for multi-admin governance approval flows.
+
+### List Pending Changes
+
+```
+GET /admin/realms/{realm}/tide-admin/change-set/users/requests
+GET /admin/realms/{realm}/tide-admin/change-set/roles/requests
+GET /admin/realms/{realm}/tide-admin/change-set/clients/requests
+GET /admin/realms/{realm}/tide-admin/change-set/groups/requests
+GET /admin/realms/{realm}/tide-admin/change-set/all/requests
+GET /admin/realms/{realm}/tide-admin/change-set/counts
+```
+
+### Sign and Commit
+
+```
+POST /admin/realms/{realm}/tide-admin/change-set/sign
+Body: { "changeSetId": "...", "changeSetType": "...", "actionType": "..." }
+
+POST /admin/realms/{realm}/tide-admin/change-set/commit
+Body: { "changeSetId": "...", "changeSetType": "...", "actionType": "..." }
+```
+
+Batch variants: `/sign/batch` and `/commit/batch` with `{ "changeSets": [...] }`.
+
+### Cancel
+
+```
+POST /admin/realms/{realm}/tide-admin/change-set/cancel
+Body: { "changeSetId": "...", "changeSetType": "...", "actionType": "..." }
+```
+
+### Approve/Reject (multi-admin)
+
+```
+POST /admin/realms/{realm}/tideAdminResources/add-review
+Content-Type: multipart/form-data
+Fields: changeSetId, changeSetType, actionType, requests
+
+POST /admin/realms/{realm}/tide-admin/add-rejection
+Content-Type: multipart/form-data
+Fields: changeSetId, actionType, changeSetType
+```
+
+Note: `add-review` and `add-rejection` use `multipart/form-data`. All other change-set endpoints use JSON.
+
+### Activity and Comments
+
+```
+GET  /admin/realms/{realm}/tide-admin/change-set/{id}/activity
+POST /admin/realms/{realm}/tide-admin/change-set/{id}/comments
+Body: { "comment": "..." }
+```
+
+---
+
+## Policy and Contract Endpoints
+
+### Policy Templates
+
+```
+POST   /admin/realms/{realm}/tide-admin/policy-templates
+GET    /admin/realms/{realm}/tide-admin/policy-templates
+PUT    /admin/realms/{realm}/tide-admin/policy-templates/{id}
+DELETE /admin/realms/{realm}/tide-admin/policy-templates/{id}
+```
+
+Body: `{ name, description, contractCode, modelId, parameters }`
+
+### Realm Policy
+
+```
+GET    /admin/realms/{realm}/tide-admin/realm-policy
+POST   /admin/realms/{realm}/tide-admin/realm-policy/pending
+POST   /admin/realms/{realm}/tide-admin/realm-policy/commit
+POST   /admin/realms/{realm}/tide-admin/realm-policy/request-delete
+POST   /admin/realms/{realm}/tide-admin/realm-policy/commit-delete
+DELETE /admin/realms/{realm}/tide-admin/realm-policy
+```
+
+### SSH Policies (per-role)
+
+```
+PUT    /admin/realms/{realm}/tide-admin/ssh-policies
+GET    /admin/realms/{realm}/tide-admin/ssh-policies
+DELETE /admin/realms/{realm}/tide-admin/ssh-policies?roleId={id}
+```
+
+Body: `{ roleId, contractCode, approvalType, executionType, threshold, policyData }`
+
+### Forseti Contracts
+
+```
+PUT /admin/realms/{realm}/tide-admin/forseti-contracts
+GET /admin/realms/{realm}/tide-admin/forseti-contracts
+```
+
+Body: `{ contractCode, name }`
+
+### Role Init Cert
+
+```
+POST /admin/realms/{realm}/tide-admin/role-policy/{roleId}/init-cert
+Body: { initCert, initCertSig }
+```
+
+---
+
+## VRK and Licensing Endpoints
+
+Infrastructure-level. Used during initial setup and license rotation.
+
+```
+POST /admin/realms/{realm}/vendorResources/generate-initial-key
+POST /admin/realms/{realm}/vendorResources/generate-initial-vrk-v1
+POST /admin/realms/{realm}/vendorResources/confirm-initial-vrk
+POST /admin/realms/{realm}/vendorResources/rotate-vrk
+POST /admin/realms/{realm}/vendorResources/switch-vrk
+POST /admin/realms/{realm}/vendorResources/requestFreeTierLicense
+GET  /admin/realms/{realm}/vendorResources/isPendingLicenseActive
+GET  /admin/realms/{realm}/vendorResources/getLicenseDetails
+GET  /admin/realms/{realm}/vendorResources/licenseHistory
+```
+
+---
+
+## Utility Endpoints
+
+```
+POST /admin/realms/{realm}/vendorResources/sign-message
+  FormParam: data
+
+GET /admin/realms/{realm}/vendorResources/get-tide-jwk
+
+POST /admin/realms/{realm}/tide-admin/generate-default-user-context
+  Body: [clientId1, clientId2, ...]
+
+POST /admin/realms/{realm}/tide-admin/what-if-token
+  Body: { changeSetType, actionType, userId, clientId }
+
+GET /admin/realms/{realm}/tide-admin/user-context/{userId}/{clientId}
+GET /admin/realms/{realm}/tide-admin/change-set/{changeSetId}/user-context
+```
+
+---
+
+## Branding Endpoints
+
+```
+POST   /admin/realms/{realm}/tide-idp-admin-resources/images/upload
+  Multipart: fileData, fileName, fileType
+
+DELETE /admin/realms/{realm}/tide-idp-admin-resources/images/{type}/delete
+GET    /admin/realms/{realm}/tide-idp-admin-resources/images/{type}/name
+GET    /realms/{realm}/tide-idp-resources/images/{type}
+```