auth

Return the calling user's effective BriteCore permissions.

Code
Designed for external MCP / OAuth consumers (notably the bc-public
server) that need to project the caller's BriteCore RBAC
state into their own authorization layer (e.g. populating
``principal.scopes`` for FastMCP's per-tool ``auth=`` checks).

The projection itself is owned by
``service.permission_projection.PermissionProjectionService``, which
iterates ``get_mapped_permissions()`` and calls ``check_permissions``
per path -- the same dispatcher pattern as
``settings.retrieve_permissions``. This is the only path
that works consistently across ``PermissionEngineV1`` (returns a
permission tree dict) and ``PermissionEngineV2`` (returns
``PermissionPolicy`` tuples) without us re-implementing engine
semantics. See ``docs/api/auth-me-permissions-spec.md`` section 2.
This handler only delegates, sets the Cache-Control transport header,
and returns the service payload.

Returns
-------
success : bool
    True if the request was successful.
messages : list of str
    Error messages.
data : dict
    permissions : list of str
        Effective permission strings in ``{path}:{access}`` form
        (e.g. ``"britecore/tasks:r"``). Each path appears at most
        once: ``:rw`` when the user has read+write, ``:r`` when
        read-only, omitted when neither. Sorted alphabetically. The
        enumerated registry includes the auto-discovered
        ``api/v2/{module}/{function}`` paths on every tenant,
        regardless of the v2-permission enforcement setting.
    engine_version : str
        The active permission engine version (``"v1"`` or ``"v2"``,
        from the ``permissions/engine-version`` setting).
    default_allow : bool
        True when the active engine allows paths that no rule
        matches: for V1 (open-world), and for V2 when
        ``permissions/permission-v2-restriction`` is off. False for
        restrictive V2 and for any unrecognized engine version
        (fail closed). Scope: this flag describes paths OUTSIDE the
        enumerated registry. A registered path is emitted whenever
        the engine allows it, so its absence means the engine denied
        it (or its evaluation failed and it was omitted) regardless
        of this flag; consumers should treat a missing registered
        path as a denial, and apply ``default_allow`` only to claims
        the registry does not cover. Because every ``api/v2/...``
        path is registered, an absent ``api/v2/...`` claim must
        never be authorized from this flag. Even for unregistered
        paths the flag is only the no-rule fallback: a parent or
        wildcard ``none`` rule still denies the children it matches.
    role_id : str or None
        The selected role id.
    role : str or None
        The role name the session selected (``chosenRole`` from
        ``web.ctx.uinfo``). Echoed for the consumer's audit log; the
        permission evaluation itself reads session context directly
        via ``check_permissions``, not this field.
    role_selection_required : bool
        True when a multi-role OAuth user has not selected a role.
    as_of : str
        ISO 8601 UTC timestamp at which the permission list was
        computed; trailing ``Z``.

Return roles available to the current OAuth grant.

Code
The caller identity and OAuth grant are read from ``web.ctx.uinfo``;
clients do not supply contact, client, or grant identifiers.

Returns
-------
success : bool
    True if the request was successful.
messages : list of str
    Error messages.
data : dict
    roles : list of dict
        Login-capable roles assigned to the authenticated contact. Each
        item contains string ``id`` and ``name`` fields.
    selected_role : dict or None
        The role already selected for this OAuth grant, with string
        ``id`` and ``name`` fields, or None when no role is selected.
    selection_required : bool
        True when the caller has multiple eligible roles and this OAuth
        grant has not selected one.
    selection_status : str
        One of ``selected``, ``selection_required``, or
        ``no_eligible_role``.

Return a list of all permission levels.

Code
Returns
-------
success: bool
    True if the request was successful
messages: list of str
    Error messages
data: list of dict
    id: str, id of the permission level
    name: str, name of the permission level

Bind one eligible role to the current OAuth grant.

Code
Parameters
----------
role_id : str
    Exact role identifier returned by ``retrieve_my_roles``.

Returns
-------
success : bool
    True if the role was selected.
messages : list of str
    Empty on success. Validation failures are returned by
    ``@api_request`` as a message dict containing ``_base_`` and ``code``.
data : dict
    selected_role : dict
        Selected role with string ``id`` and ``name`` fields.
    selection_status : str
        ``created`` for a new binding or ``matched`` when the same
        role was selected previously.

Raises
------
McpRoleSelectionError
    ``OAUTH_GRANT_REQUIRED`` when OAuth grant context is missing,
    ``ROLE_NOT_ASSIGNED`` when the role is not eligible for the caller,
    or ``ROLE_ALREADY_SELECTED`` when the immutable grant binding points
    to a different role. ``@api_request`` converts these into
    ``success: false`` response envelopes.

Issue a persisted session cookie to a contact authenticated by api key.

Code
The caller must be authenticated with an api key and hold an explicit
``rw`` grant on ``auth/apiKeySession`` through its contact, one of its
user groups or its role. isGod, IWS usernames and engine defaults do not
bypass it; any other authenticated caller gets a 403 ``permissionDenied``
body and no session. That grant is the only gate: the auto-discovered
``api/v2/auth/session`` rule is not required, even on tenants that enforce
api.v2 permissions for the caller's level. A BriteAuth bearer token is refused too, although
the gateway marks it ``api_key_validated`` to spare it the CSRF check. Any
parameter besides the gateway's ``api_key`` is refused. The
session token carries ``api_key_validated``, so replaying the cookie
against ``/gateway`` endpoints skips their CSRF token check. Each
cookieless call mints exactly one session that expires on the site's
``login``/``session-timeout``; a call presenting the caller's own session
cookie reuses it, and a cookie of another identity is rotated to a new
session. The session ID is returned only in the ``Set-Cookie`` header,
never in the body, so it stays out of the ``@api_request`` result log.

Parameters
----------
**payload : dict
    Must be empty: the gateway consumes ``api_key`` before dispatch.

Returns
-------
success : bool
    True if the session was issued.
messages : list of str
    Error messages.
data : dict
    contact_id : str
        Id of the api-key contact the session belongs to.
    username : str
        Username of that contact.
    expires_in : int
        Session lifetime in seconds.
    created : bool
        True when this call minted a new session; False when it reused
        the presented session cookie.

Raises
------
BCValidationError
    When a parameter is passed. ``@api_request`` answers with the
    standard error envelope.
BCApiRequestPermissionDeniedError
    When the caller is not authenticated with an api key or holds no
    explicit ``rw`` grant on ``auth/apiKeySession``. ``@api_request``
    answers with the ``permissionDenied`` body under a 403 status.