pkg-auth 3.0.0__py3-none-any.whl

pkg_auth/authorization/adapters/sqlalchemy/migrations/versions/20260412_0002_add_permission_is_platform.py

@@ -0,0 +1,39 @@
+"""Add is_platform flag to permissions.
+
+Revision ID: pkg_auth_acl_0002
+Revises: pkg_auth_acl_0001
+Create Date: 2026-04-12 00:00:00.000000
+
+Adds the ``is_platform`` boolean column so the central ACL UI can
+filter platform-only permissions out of org-scoped role builders.
+Defaults to ``false`` so existing rows remain valid and backwards-
+compatible 2-tuple registration calls keep working.
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "pkg_auth_acl_0002"
+down_revision: Union[str, None] = "pkg_auth_acl_0001"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "permissions",
+        sa.Column(
+            "is_platform",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("permissions", "is_platform")

pkg_auth/authorization/adapters/sqlalchemy/migrations/versions/20260620_0003_permission_visibility.py

@@ -0,0 +1,65 @@
+"""Replace permissions.is_platform with a tri-state visibility column.
+
+Revision ID: pkg_auth_acl_0003
+Revises: pkg_auth_acl_0002
+Create Date: 2026-06-20 00:00:00.000000
+
+``is_platform`` was a 2-state flag (platform-only vs everywhere). It is
+replaced by a ``visibility`` enum-as-string:
+
+    - ``platform_only`` (was ``is_platform = true``)
+    - ``shared``        (was ``is_platform = false``, the default)
+    - ``tenant_only``   (new — hidden from the platform org)
+
+Backfill maps the old boolean, then the old column is dropped.
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "pkg_auth_acl_0003"
+down_revision: Union[str, None] = "pkg_auth_acl_0002"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "permissions",
+        sa.Column(
+            "visibility",
+            sa.String(32),
+            nullable=False,
+            server_default=sa.text("'shared'"),
+        ),
+    )
+    op.execute(
+        "UPDATE permissions SET visibility = "
+        "CASE WHEN is_platform THEN 'platform_only' ELSE 'shared' END"
+    )
+    op.create_index(
+        "ix_permissions_visibility", "permissions", ["visibility"]
+    )
+    op.drop_column("permissions", "is_platform")
+
+
+def downgrade() -> None:
+    op.add_column(
+        "permissions",
+        sa.Column(
+            "is_platform",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+    )
+    op.execute(
+        "UPDATE permissions SET is_platform = "
+        "(visibility = 'platform_only')"
+    )
+    op.drop_index("ix_permissions_visibility", table_name="permissions")
+    op.drop_column("permissions", "visibility")

pkg_auth/authorization/adapters/sqlalchemy/migrations/versions/20260620_0004_permission_description_jsonb.py

@@ -0,0 +1,52 @@
+"""Localize permissions.description: TEXT -> JSONB locale map.
+
+Revision ID: pkg_auth_acl_0004
+Revises: pkg_auth_acl_0003
+Create Date: 2026-06-20 00:00:01.000000
+
+``description`` becomes a JSONB ``{locale: text}`` map. Existing plain-text
+descriptions are backfilled under the default locale, read from the
+``ACL_DEFAULT_LOCALE`` env var at migration time (fallback ``"en"``).
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import Sequence, Union
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "pkg_auth_acl_0004"
+down_revision: Union[str, None] = "pkg_auth_acl_0003"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_LOCALE_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_-]*$")
+
+
+def _default_locale() -> str:
+    loc = os.environ.get("ACL_DEFAULT_LOCALE") or "en"
+    if not _LOCALE_RE.match(loc):
+        raise ValueError(f"Invalid ACL_DEFAULT_LOCALE {loc!r}")
+    return loc
+
+
+def upgrade() -> None:
+    locale = _default_locale()
+    op.execute(
+        f"ALTER TABLE permissions "
+        f"ALTER COLUMN description TYPE JSONB USING "
+        f"CASE WHEN description IS NULL OR description = '' THEN NULL "
+        f"ELSE jsonb_build_object('{locale}', description) END"
+    )
+
+
+def downgrade() -> None:
+    locale = _default_locale()
+    op.execute(
+        f"ALTER TABLE permissions "
+        f"ALTER COLUMN description TYPE TEXT USING "
+        f"COALESCE(description ->> '{locale}', "
+        f"(SELECT value FROM jsonb_each_text(description) LIMIT 1))"
+    )

pkg_auth/authorization/adapters/sqlalchemy/migrations/versions/20260620_0005_services_tables.py

@@ -0,0 +1,116 @@
+"""Create services and organization_services tables (service guard).
+
+Revision ID: pkg_auth_acl_0005
+Revises: pkg_auth_acl_0004
+Create Date: 2026-06-20 00:00:02.000000
+
+``services`` is the vendor-controlled service registry; ``auto_provision``
+and ``saas_available`` are set only via ``pkg-auth-sync-services``.
+``organization_services`` is the per-org entitlement that drives the
+default-deny service guard in ``ResolveAuthContextUseCase``.
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects.postgresql import JSONB
+
+# revision identifiers, used by Alembic.
+revision: str = "pkg_auth_acl_0005"
+down_revision: Union[str, None] = "pkg_auth_acl_0004"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "services",
+        sa.Column(
+            "id",
+            sa.Uuid(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column("name", sa.String(64), nullable=False),
+        sa.Column("display_label", JSONB, nullable=True),
+        sa.Column(
+            "auto_provision",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+        sa.Column(
+            "saas_available",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.UniqueConstraint("name", name="uq_services_name"),
+    )
+    op.create_index("ix_services_name", "services", ["name"])
+
+    op.create_table(
+        "organization_services",
+        sa.Column(
+            "id",
+            sa.Uuid(as_uuid=True),
+            primary_key=True,
+            server_default=sa.text("gen_random_uuid()"),
+        ),
+        sa.Column("organization_id", sa.Uuid(as_uuid=True), nullable=False),
+        sa.Column("service_name", sa.String(64), nullable=False),
+        sa.Column(
+            "enabled",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("true"),
+        ),
+        sa.Column(
+            "source",
+            sa.String(16),
+            nullable=False,
+            server_default=sa.text("'manual'"),
+        ),
+        sa.Column(
+            "granted_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.ForeignKeyConstraint(
+            ["organization_id"], ["organizations.id"], ondelete="CASCADE"
+        ),
+        sa.UniqueConstraint(
+            "organization_id", "service_name",
+            name="uq_org_services_org_service",
+        ),
+    )
+    op.create_index(
+        "ix_org_services_org_id",
+        "organization_services",
+        ["organization_id"],
+    )
+    op.create_index(
+        "ix_org_services_service_name",
+        "organization_services",
+        ["service_name"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("organization_services")
+    op.drop_table("services")

pkg_auth/authorization/adapters/sqlalchemy/migrations/versions/__init__.py

@@ -0,0 +1 @@
+"""Alembic migration version files (branch_labels=('pkg_auth_acl',))."""

pkg_auth/authorization/adapters/sqlalchemy/mixins.py

@@ -0,0 +1,187 @@
+"""Abstract column mixins for the ACL ORM models.
+
+These mixins provide the ACL-essential columns without defining ``id``,
+``__tablename__``, FK columns, or relationships. Consuming services
+extend them by creating a concrete model class that inherits from both
+their own ``DeclarativeBase`` and the appropriate mixin.
+
+Example (service extends UserMixin)::
+
+    from pkg_auth.authorization.adapters.sqlalchemy.mixins import UserMixin
+
+    class OrmUser(Base, UserMixin):
+        __tablename__ = "users"
+        id: Mapped[UUID] = mapped_column(Uuid, primary_key=True)
+        # UserMixin columns inherited automatically
+        # Add service-specific columns:
+        username: Mapped[str] = mapped_column(String(255))
+        bio: Mapped[str | None] = mapped_column(Text)
+
+Services that do NOT need to extend use the default concrete models in
+``models.py`` which already inherit these mixins.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import Boolean, DateTime, String, Text, func, text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+class UserMixin:
+    """ACL columns for the users table."""
+
+    keycloak_sub: Mapped[str] = mapped_column(
+        String(64), unique=True, index=True
+    )
+    email: Mapped[str] = mapped_column(String(255), index=True)
+    full_name: Mapped[str | None] = mapped_column(String(255))
+    first_seen_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    last_seen_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+
+class OrganizationMixin:
+    """ACL columns for the organizations table."""
+
+    slug: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    name: Mapped[str] = mapped_column(String(255))
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+
+class PermissionMixin:
+    """ACL columns for the permissions (catalog) table.
+
+    ``visibility`` controls which role builders may see/use the permission:
+    ``platform_only`` (platform org only), ``shared`` (everywhere, default),
+    or ``tenant_only`` (normal orgs only — hidden from the platform org).
+    Consuming services declare it inline via :class:`CatalogEntry`; the
+    central ACL UI filters by it via the ``scope=`` argument on the catalog
+    repo. ``description`` is a localized JSONB map (``{locale: text}``).
+    """
+
+    key: Mapped[str] = mapped_column(String(255), unique=True, index=True)
+    service_name: Mapped[str] = mapped_column(String(64), index=True)
+    description: Mapped[dict | None] = mapped_column(JSONB)
+    visibility: Mapped[str] = mapped_column(
+        String(32),
+        nullable=False,
+        default="shared",
+        server_default=text("'shared'"),
+        index=True,
+    )
+    registered_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+
+class ServiceMixin:
+    """ACL columns for the ``services`` table (the service registry).
+
+    ``auto_provision`` and ``saas_available`` are vendor-controlled and set
+    only via the ``pkg-auth-sync-services`` path. ``display_label`` is a
+    localized JSONB map.
+    """
+
+    name: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    display_label: Mapped[dict | None] = mapped_column(JSONB)
+    auto_provision: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=False,
+        server_default=text("false"),
+    )
+    saas_available: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=False,
+        server_default=text("false"),
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+
+class OrganizationServiceMixin:
+    """ACL columns for the ``organization_services`` table (per-org service
+    entitlements). FK columns and the ``(organization_id, service_name)``
+    unique constraint live on the concrete model.
+    """
+
+    service_name: Mapped[str] = mapped_column(String(64), index=True)
+    enabled: Mapped[bool] = mapped_column(
+        Boolean,
+        nullable=False,
+        default=True,
+        server_default=text("true"),
+    )
+    source: Mapped[str] = mapped_column(
+        String(16), nullable=False, server_default=text("'manual'")
+    )
+    granted_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+
+
+class RoleMixin:
+    """ACL columns for the roles table."""
+
+    name: Mapped[str] = mapped_column(String(128))
+    description: Mapped[str | None] = mapped_column(Text)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )
+
+
+class MembershipMixin:
+    """ACL columns for the memberships table.
+
+    Does NOT include ``status`` — services define their own status type
+    (string, enum, etc.). Does NOT include FK columns or relationships
+    — those depend on the concrete model's schema and table names.
+    """
+
+    joined_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+        onupdate=func.now(),
+    )