ebuilder-sql-query-security-error-handling

name	ebuilder-sql-query-security-error-handling
description	Security and error-handling playbook for query-* definitions in configs/sql.*.yml. USE FOR: datasource selection, authorize policies/roles/path, catchErrors mapping, and on success/error callbacks. DO NOT USE FOR: output shaping internals or pre/post pipeline design.

eBuilder Query Security and Error Handling

Purpose

Use this skill for secure query access control and predictable failure behavior.

Scope

• datasource correctness.
• authorize policies, roles, and path-based rules.
• catchErrors mapping.
• on.success and on.error callbacks.

Authorization Patterns

Use one of:

• Policy-based: authorize.policy.
• Role-based: authorize: - role: ....
• Path-based: authorize.path.

Apply authorization whenever query results include sensitive or user-scoped data.

Error Mapping

Use catchErrors to translate expected DB/application errors into stable HTTP/API responses. Avoid mapping unknown codes without intent.

Callback Usage

Use on.success for audit/telemetry side effects. Use on.error for controlled logging or remediation tasks.

Example

query:
  query-item:
    datasource: main
    authorize:
      policy: eClient
    responseType: singleOrNull
    command: |
      SELECT id AS "id", title AS "title"
      FROM items
      WHERE id = ${itemId}
    catchErrors:
      20001:
        statusCode: 400
        message: INVALID_ITEM_ID
    on:
      success:
        - task: task-log-access
          params:
            itemId: ${itemId}

Deterministic Checks

1. datasource key exists in configs/app.yml.
2. authorize references valid policies/roles/paths.
3. catchErrors covers only known, expected codes.
4. Callback tasks are idempotent and safe.
5. Query output does not bypass security policy intent.