GraphQL Query Sanitization

Resource aliasing allows one module to rename another module’s resources. After aliasing, the actual GraphQL schema uses the target resource name (dns_auth) while the dependent module’s source still refers to the logical name (auth).

rescile-ce and rescile-ee provide a built-in endpoint that rewrites a query so that modules do not have to manage this themselves.

Endpoint

POST /api/graphql/sanitize
Content-Type: application/json

{
  "module": "mm-hybriddns",
  "query": "{ auth { name } resident { name auth { node { name } } } }"
}

Response:

{
  "ok": true,
  "module": "mm-hybriddns",
  "query": "{ dns_auth { name } resident { name dns_auth { node { name } } } }",
  "aliases_applied": {
    "auth": "dns_auth"
  },
  "removed": {
    "fields": [],
    "types": []
  },
  "attempts": 0
}

The endpoint:

1. Loads the alias map defined for the requesting module.
2. Substitutes logical resource names with the aliased names.
3. Validates the query against the current schema.
4. Strips unknown fields and types using the same resilience loop that powers x-resilient-graphql.
5. Returns the final, safe query string together with metadata about what changed.

When to use it

Use this endpoint when a module’s frontend:

• hardcodes GraphQL queries using the module’s own resource names,
• is composed into a stack where those resources may be aliased by another module,
• wants graceful degradation when optional resources or fields are absent.

Using it from @ucs/sdk

import { sanitizeGraphQL, useGraphQuery } from '@ucs/sdk';

async function loadData(moduleId) {
  const raw = `{ auth { name } }`;
  const { query, ok } = await sanitizeGraphQL(moduleId, raw);
  if (!ok) return null;
  return useGraphQuery(['gql', 'auth'], query);
}

Limitations

• Mutations are rejected. The endpoint is read-only and returns 400 Bad Request if the query appears to be a mutation.
• Whole-word substitution. Aliases are applied as whole-word replacements. If a non-resource field happens to share the same token as a logical resource name, it may be renamed and then stripped. We recommend keeping resource names distinct.
• No unused-fragment cleanup. Only unknown fields and types are removed. Unused fragments are left untouched.
• CE/EE only in this version. The endpoint is available in rescile-ce and rescile-ee. Standalone rescile-controller and rescile-mcp-server do not expose it unless the alias map is persisted alongside the graph.

Alternative: output artifacts

For cases where the frontend needs more than query rewriting — for example, a stable configuration object consumed outside the browser — defining an [output] generator is still the most robust solution. See Resource Aliasing for Apps for that pattern.