Class ClientChannelsMetaData

java.lang.Object
com.kingsrook.qqq.backend.core.model.metadata.permissions.ClientChannelsMetaData
All Implemented Interfaces:
MetaDataProducerOutput, QMetaDataObject, QSupplementalInstanceMetaData, TopLevelMetaDataInterface, Serializable
public class ClientChannelsMetaData extends Object implements QSupplementalInstanceMetaData
Client channels: which clients (Next UI, the AI assistant, a CLI...) may call the UI API, and which objects are always denied to a channel, whatever the human user's permissions. - A request names its client in the X-QQQ-Client header (`channel[/detail]`, e.g. `next-ui`, `assistant/turn-42`); the channel must be one of getChannels(). The server stores it on the QSession (QSession.clientChannel); it is written to audits. The actor is always the human user: a channel never grants anything. - Deny rules: QPermissionRules.withDeniedClients on an object, deniedObjects here by exact name, and deniedPatterns here by name glob (`*` wildcard), over tables, processes, reports, widgets and apps. A denied object is handled as if the user had no permission: omitted from metadata, and its operations refused (PermissionsHelper). - Fail-closed: when an instance registers nothing, defaults() applies - including the assistant wall (its own configuration, identity and permission administration, audits, API keys, credentials and secrets). Only code or admin metadata changes these rules; a client cannot remove its own channel label (UiApiInvoker sets it server side). See docs/UI-API-CLIENT-CHANNELS.md.
See Also:

  • Field Details

    • NAME

      public static final String NAME
      See Also:

    • CHANNEL_NEXT_UI

      public static final String CHANNEL_NEXT_UI
      See Also:

    • CHANNEL_MATERIAL_DASHBOARD

      public static final String CHANNEL_MATERIAL_DASHBOARD
      See Also:

    • CHANNEL_ASSISTANT

      public static final String CHANNEL_ASSISTANT
      See Also:

    • CHANNEL_CLI

      public static final String CHANNEL_CLI
      See Also:

    • CHANNEL_TUI

      public static final String CHANNEL_TUI
      See Also:

    • CHANNEL_IOS

      public static final String CHANNEL_IOS
      See Also:

    • CHANNEL_API

      public static final String CHANNEL_API
      See Also:

    • CHANNEL_TOKEN

      public static final String CHANNEL_TOKEN
      See Also:

    • AUDIT_PATTERN

      public static final String AUDIT_PATTERN
      core's audit tables (audit, auditDetail, ...): denied to the assistant by default; withAssistantAuditReads() makes them readable, never writable
      See Also:

    • ASSISTANT_GENERIC_DENIED_PATTERNS

      public static final List<String> ASSISTANT_GENERIC_DENIED_PATTERNS
      the assistant's generic default deny patterns - security surfaces any application may have, whoever defines them (lower-cased globs)

    • ASSISTANT_TRANSITIONAL_QBIT_DENIED_PATTERNS

      public static final List<String> ASSISTANT_TRANSITIONAL_QBIT_DENIED_PATTERNS
      TRANSITIONAL: qbit-specific assistant denies, kept in core only until each qbit's producer registers its own rule (QRun-IO/qqq#1157) - each qbit owns its wall from its next release; these are removed at 4.1.0 GA. They stay here meanwhile so the wall never opens (fail-closed) for an application still on an older qbit.

    • ASSISTANT_DEFAULT_DENIED_PATTERNS

      public static final List<String> ASSISTANT_DEFAULT_DENIED_PATTERNS
      every assistant deny pattern applied by default (generic + transitional)

    • SENSITIVE_TABLE_PATTERNS

      public static final List<String> SENSITIVE_TABLE_PATTERNS
      table-name globs that look sensitive (configuration, policy, secrets, tokens): the validator warns when one is not denied to the assistant

    • ASSISTANT_DEFAULT_WRITE_DENIED_PATTERNS

      public static final List<String> ASSISTANT_DEFAULT_WRITE_DENIED_PATTERNS
      the assistant's default write-deny patterns: never insertable, editable or deletable - no tampering - even when a host opts in to reading them (withAssistantAuditReads)

  • Constructor Details

    • ClientChannelsMetaData

      public ClientChannelsMetaData()

  • Method Details

    • defaults

      public static ClientChannelsMetaData defaults()
      The defaults: the standard channels, and the assistant wall.

    • of

      public static ClientChannelsMetaData of(QInstance qInstance)
      The instance's registry - or, when nothing registered one, the defaults (so the assistant wall always applies).

    • ofOrWithNew

      public static ClientChannelsMetaData ofOrWithNew(QInstance qInstance)
      The instance's registry, adding the defaults first if it has none - for modules that add channels or deny rules.

    • getName

      public String getName()
      Specified by:
      getName in interface TopLevelMetaDataInterface

    • channelName

      public static String channelName(String clientChannel)
      The channel name of a channel value (`assistant/turn-42` -> `assistant`).

    • isAllowedChannel

      public boolean isAllowedChannel(String channelName)
      Whether a channel name is allowed (registered).

    • isDenied

      public boolean isDenied(String channelName, String objectName, QPermissionRules effectiveRules)
      Whether an object (by kind and name, and its effective permission rules) is denied to a channel. A null channel is never denied here.

    • isWriteDenied

      public boolean isWriteDenied(String channelName, String objectName, QPermissionRules effectiveRules)
      Whether writes (insert, edit, delete) to an object are denied to a channel (it may still be read). A fully denied object is write-denied too.

    • withDeniedWritePattern

      public ClientChannelsMetaData withDeniedWritePattern(String channelName, String pattern)
      Deny a channel writes (insert, edit, delete) to every object whose name matches a `*` glob - reads stay allowed.

    • getDeniedWritePatterns

      public Map<String,List<String>> getDeniedWritePatterns()
      Getter for deniedWritePatterns (channel to name globs)

    • findUnwalledSensitiveTables

      public static List<String> findUnwalledSensitiveTables(QInstance qInstance)
      Tables whose names look sensitive (SENSITIVE_TABLE_PATTERNS) but that no rule denies to the assistant - each should either be walled by its qbit (withDeniedObject / withDeniedPattern / QPermissionRules.withDeniedClients) or be reviewed as safe (withReviewedObject).

    • warnUnwalledSensitiveTables

      public static void warnUnwalledSensitiveTables(QInstance qInstance, QInstanceValidator validator)
      Validator warnings for findUnwalledSensitiveTables (called for every instance, whether or not it registers a ClientChannelsMetaData).

    • withReviewedObject

      public ClientChannelsMetaData withReviewedObject(String channelName, String objectName)
      Record that an object was reviewed as safe for a channel (silences the sensitive-table warning; grants nothing).

    • withChannel

      public ClientChannelsMetaData withChannel(String name, String description)
      Allow a channel.

    • withDeniedObject

      public ClientChannelsMetaData withDeniedObject(String channelName, String objectName)
      Deny a channel one object (table, process, report, widget or app) by name.

    • withAssistantAuditReads

      public ClientChannelsMetaData withAssistantAuditReads()
      Host opt-in: let the assistant READ the audit tables (audit*), e.g. for a record-history tool. They stay write-denied (no tampering), and the user's own audit permissions still apply. By default the assistant cannot see audits at all. Call it on the instance's own registry (ofOrWithNew), never on the shared defaults.

    • withDeniedPattern

      public ClientChannelsMetaData withDeniedPattern(String channelName, String pattern)
      Deny a channel every object whose name matches a `*` glob.

    • withFieldAccessPolicy

      public ClientChannelsMetaData withFieldAccessPolicy(String channelName, QCodeReference policy)
      Register a channel policy by code reference. Invalid policies fail closed.

    • withFieldAccessPolicy

      public ClientChannelsMetaData withFieldAccessPolicy(String channelName, FieldAccessChannelPolicyInterface policy)
      Register a channel policy instance.

    • getFieldAccessPolicy

      public FieldAccessChannelPolicyInterface getFieldAccessPolicy(String channelName)
      Resolve a policy once, never its per-session decisions. The assistant has a default even when the instance has registered no channel metadata.

    • getChannels

      public Map<String,String> getChannels()
      Getter for channels (name to description)

    • getDeniedObjects

      public Map<String,Set<String>> getDeniedObjects()
      Getter for deniedObjects (channel to object names)

    • getDeniedPatterns

      public Map<String,List<String>> getDeniedPatterns()
      Getter for deniedPatterns (channel to name globs)

    • validate

      public void validate(QInstance qInstance, QInstanceValidator validator)
      Channel names must be lowercase a-z, 0-9 and '-'; deny rules must name allowed channels; denied object names should exist.
      Specified by:
      validate in interface QSupplementalInstanceMetaData