simple-module-api-tokens 0.0.37__py3-none-any.whl

api_tokens/locales/en.json

@@ -0,0 +1,104 @@
+{
+  "nav": {
+    "api_tokens": "API tokens"
+  },
+  "audit": {
+    "token": "API token"
+  },
+  "errors": {
+    "session_required": "API tokens can only be managed from a signed-in browser session, not with a token.",
+    "scopes_required": "Choose at least one scope.",
+    "scope_not_held": "You cannot grant the scope \"{value}\": you do not hold it.",
+    "role_forbidden": "A service key cannot have the \"{role}\" role.",
+    "role_not_assignable": "The role \"{value}\" cannot be given to a service key.",
+    "lifetime_too_long": "A token can be valid for at most {days} days.",
+    "invalid_kind": "This kind of token cannot be created here.",
+    "tenant_required": "Choose an organisation before managing its tokens.",
+    "not_found": "Token not found.",
+    "account_required": "Your account has no local user record, so a personal access token could never sign in as you. Ask an administrator for a service key instead."
+  },
+  "index": {
+    "title": "API tokens",
+    "description": "Personal access tokens let scripts and tools call the API as you, limited to the scopes you choose.",
+    "usage": "Send a token in the Authorization header: Authorization: Bearer <token>."
+  },
+  "admin": {
+    "title": "API tokens",
+    "description": "Every personal access token and service key in this organisation.",
+    "tenant_required": "Choose an organisation to see and create its API tokens.",
+    "new_service_key": "New service key"
+  },
+  "list": {
+    "name": "Name",
+    "token": "Token",
+    "kind": "Kind",
+    "owner": "Owner",
+    "scopes": "Scopes",
+    "roles": "Roles",
+    "expires": "Expires",
+    "last_used": "Last used",
+    "status": "Status",
+    "actions": "Actions",
+    "never": "Never",
+    "revoke": "Revoke",
+    "empty_title": "No API tokens yet",
+    "empty_description": "Create a token to call the API from a script or another service.",
+    "scope_count_one": "{count} scope",
+    "scope_count_other": "{count} scopes"
+  },
+  "kind": {
+    "personal": "Personal",
+    "service": "Service key"
+  },
+  "status": {
+    "active": "Active",
+    "revoked": "Revoked",
+    "expired": "Expired"
+  },
+  "form": {
+    "new_token": "New token",
+    "create_title": "Create a personal access token",
+    "create_service_title": "Create a service key",
+    "create_description": "The token can do only what its scopes allow, and never more than you can.",
+    "create_service_description": "A service key acts for no person. It gets the roles you pick, limited to the scopes you choose.",
+    "name": "Name",
+    "name_placeholder": "e.g. CI deploy",
+    "scopes": "Scopes",
+    "scopes_hint": "Only permissions you hold are listed.",
+    "roles": "Roles",
+    "roles_hint": "The administrator role cannot be given to a service key.",
+    "no_roles": "No assignable roles.",
+    "expiry": "Expires after",
+    "days_one": "{count} day",
+    "days_other": "{count} days",
+    "submit": "Create token",
+    "cancel": "Cancel"
+  },
+  "created": {
+    "title": "Copy your new token",
+    "warning": "This is the only time the token is shown. Store it somewhere safe now — it cannot be recovered.",
+    "copy": "Copy",
+    "copied": "Copied",
+    "done": "Done"
+  },
+  "revoke": {
+    "title": "Revoke \"{name}\"?",
+    "description": "Anything using this token stops working on its next request. This cannot be undone.",
+    "confirm": "Revoke",
+    "cancel": "Cancel"
+  },
+  "toasts": {
+    "created": "Token created",
+    "revoked": "Token revoked",
+    "failed": "Something went wrong. Please try again.",
+    "revoked_all_one": "{count} token revoked",
+    "revoked_all_other": "{count} tokens revoked"
+  },
+  "revoke_all": {
+    "button": "Revoke all",
+    "title": "Revoke all your tokens?",
+    "description": "Every personal access token you hold stops working on its next request, in every organisation. Use this if a token may have leaked: changing your password or signing out everywhere does not end tokens.",
+    "confirm": "Revoke all",
+    "cancel": "Cancel"
+  }
+}

api_tokens/models.py

@@ -0,0 +1,58 @@
+"""SQLModel tables for the api_tokens module.
+
+One table holds both credential kinds. Only ``sha256(token)`` is stored; the
+secret itself is shown once, in the response that created it, and nowhere
+else. ``prefix`` is a short, non-secret slice so a person can tell their
+tokens apart in a list.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import ClassVar
+
+import sqlalchemy as sa
+from fastapi_users_db_sqlalchemy.generics import GUID
+from simple_module_db.base import create_module_base
+from simple_module_db.mixins import AuditMixin, MultiTenantMixin
+from simple_module_db.types import AwareDateTime
+from sqlalchemy import Index
+from sqlmodel import Field
+
+from api_tokens.constants import IX_TOKEN_HASH, NAME_MAX_LENGTH, TABLE_TOKEN, TokenKind
+
+Base = create_module_base("api_tokens")
+
+
+class ApiToken(Base, AuditMixin, MultiTenantMixin, table=True):  # ty: ignore[unsupported-base]
+    """A personal access token or a service API key."""
+
+    __tablename__ = TABLE_TOKEN
+    # The hash is a credential-equivalent lookup key and ``last_used_at`` is
+    # bumped by a Core UPDATE that never reaches the audit listener anyway;
+    # neither belongs in the audit trail. Create and revoke still do.
+    __audit_exclude_fields__: ClassVar[set[str]] = {"token_hash", "last_used_at"}
+    # ``token_hash`` leads, so the per-request lookup by hash alone is an
+    # index seek; ``tenant_id`` is in the key because every unique key on a
+    # tenant-scoped table must be (SM024). A SHA-256 of 32 random bytes does
+    # not collide, so the wider key loses nothing.
+    __table_args__ = (Index(IX_TOKEN_HASH, "token_hash", "tenant_id", unique=True),)
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    kind: str = Field(max_length=16, default=TokenKind.PERSONAL)
+    name: str = Field(max_length=NAME_MAX_LENGTH)
+    prefix: str = Field(max_length=16)
+    # Looked up before any tenant is known — see ``__table_args__``.
+    token_hash: str = Field(max_length=64)
+    # ``GUID``, the type ``users_user.id`` has, so the values compare equal on
+    # SQLite too (``sa.Uuid`` stores bare hex there — GH #339). No foreign key:
+    # every module owns its own ``MetaData``, so one cannot name another
+    # module's table. A deleted owner is handled where it matters — the
+    # resolver finds no account and refuses the token.
+    owner_user_id: uuid.UUID | None = Field(default=None, sa_type=GUID, index=True)
+    scopes: list[str] = Field(default_factory=list, sa_type=sa.JSON())
+    roles: list[str] = Field(default_factory=list, sa_type=sa.JSON())
+    expires_at: datetime = Field(sa_type=AwareDateTime())
+    last_used_at: datetime | None = Field(default=None, sa_type=AwareDateTime())
+    revoked_at: datetime | None = Field(default=None, sa_type=AwareDateTime())

api_tokens/module.py

@@ -0,0 +1,109 @@
+"""ApiTokens module: personal access tokens and service API keys."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from simple_module_core.menu import MenuItem, MenuRegistry, MenuSection
+from simple_module_core.module import ModuleBase, ModuleMeta
+from simple_module_core.tenancy import TenantRole, tenant_role
+
+from api_tokens import constants as c
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter, FastAPI
+    from simple_module_core.audit_links import AuditLinkRegistry
+    from simple_module_core.permissions import PermissionRegistry
+
+
+class ApiTokensModule(ModuleBase):
+    meta = ModuleMeta(
+        name=c.MODULE_NAME,
+        route_prefix=c.API_PREFIX,
+        view_prefix=c.VIEW_PREFIX,
+        admin_view_prefix=c.ADMIN_VIEW_PREFIX,
+        # Auth owns the resolver chain this module appends to; Users owns the
+        # accounts a personal token acts for; Settings stores the lifetime cap.
+        depends_on=[c.MODULE_AUTH, c.MODULE_USERS, c.MODULE_SETTINGS],
+    )
+
+    def register_settings(self, app: FastAPI) -> None:
+        from api_tokens.services import ApiTokensServices
+        from api_tokens.settings import ApiTokensSettings
+
+        # SM009 is AST-based: resolve via importlib like the other
+        # settings-backed modules.
+        register_module_settings = importlib.import_module(
+            "settings.registration"
+        ).register_module_settings
+        register_module_settings(
+            app,
+            c.MODULE_PACKAGE,
+            ApiTokensSettings,
+            lambda s: ApiTokensServices(settings=s),
+        )
+
+    def register_routes(self, api_router: APIRouter, view_router: APIRouter) -> None:
+        from api_tokens.endpoints.admin_api import router as admin_api
+        from api_tokens.endpoints.api import router as api
+        from api_tokens.endpoints.views import router as views
+
+        api_router.include_router(api)
+        api_router.include_router(admin_api)
+        view_router.include_router(views)
+
+    def register_admin_routes(self, admin_router: APIRouter) -> None:
+        from api_tokens.endpoints.views import admin_router as admin_views
+
+        admin_router.include_router(admin_views)
+
+    def register_menu_items(self, registry: MenuRegistry) -> None:
+        registry.add(
+            MenuItem(
+                label=c.MENU_LABEL,
+                label_key=c.MENU_LABEL_KEY,
+                url=c.USER_URL,
+                icon=c.MENU_ICON,
+                order=c.MENU_USER_ORDER,
+                section=MenuSection.USER_DROPDOWN,
+                permissions=[c.PERM_USE],
+            )
+        )
+        registry.add(
+            MenuItem(
+                label=c.MENU_LABEL,
+                label_key=c.MENU_LABEL_KEY,
+                url=c.ADMIN_URL,
+                icon=c.MENU_ICON,
+                order=c.MENU_ADMIN_ORDER,
+                section=MenuSection.ADMIN_SIDEBAR,
+                group="Access",
+                group_key="ui.nav_groups.access",
+                permissions=[c.PERM_MANAGE],
+            )
+        )
+
+    def register_permissions(self, registry: PermissionRegistry) -> None:
+        registry.add_group(c.PERM_GROUP, [c.PERM_USE, c.PERM_MANAGE])
+        registry.map_role(c.USER_ROLE, [c.PERM_USE])
+        for role in TenantRole:
+            registry.map_role(tenant_role(role), [c.PERM_USE])
+
+    def register_audit_links(self, registry: AuditLinkRegistry) -> None:
+        from api_tokens.audit import build_token_audit_link
+
+        registry.register(build_token_audit_link())
+
+    def locale_dirs(self) -> dict[str, Path]:
+        base = Path(str(importlib.resources.files(__package__) / "locales"))
+        return {c.LOCALE_NAMESPACE: base}
+
+    async def on_startup(self, app: FastAPI) -> None:
+        from api_tokens.resolver import resolve_api_token
+
+        resolvers = app.state.auth.principal_resolvers
+        if resolve_api_token not in resolvers:
+            resolvers.append(resolve_api_token)

api_tokens/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@simple-module-py/api-tokens",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Frontend assets for the ApiTokens module",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@inertiajs/react": "^3.7.0",
+    "@simple-module-py/ui": "*"
+  },
+  "devDependencies": {
+    "@simple-module-py/tsconfig": "*"
+  },
+  "dependencies": {
+    "lucide-react": "^1.43.0",
+    "sonner": "^2.0.8"
+  }
+}

api_tokens/pages/Admin.tsx

@@ -0,0 +1,92 @@
+import { Head, usePage } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { InlineBanner } from '@simple-module-py/ui/components/InlineBanner';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { AdminLayout } from '@simple-module-py/ui/layouts/AdminLayout';
+import { Building2, Plus } from 'lucide-react';
+import { useState } from 'react';
+import { CreatedTokenDialog } from './components/CreatedTokenDialog';
+import { CreateTokenDialog } from './components/CreateTokenDialog';
+import { RevokeTokenDialog } from './components/RevokeTokenDialog';
+import { TokenTable } from './components/TokenTable';
+import { useTokenActions } from './components/useTokenActions';
+import type { CreatePayload, TokenFormProps } from './types';
+
+interface Props extends TokenFormProps {
+  roles: string[];
+  tenant_required: boolean;
+}
+
+/** Every token in the active tenant; service keys are created here. */
+function Admin() {
+  const props = usePage<{ props: Props }>().props as unknown as Props;
+  const { t } = useT();
+  const [creating, setCreating] = useState(false);
+  // An audit-log link lands here as ?token=<id>; mark that row.
+  const highlightId =
+    typeof window === 'undefined' ? null : new URLSearchParams(window.location.search).get('token');
+  const actions = useTokenActions({
+    csrfToken: props.csrf_token,
+    createUrl: `${props.api_url}/admin/service-keys`,
+    revokeUrl: (id) => `${props.api_url}/admin/tokens/${id}/revoke`,
+  });
+
+  async function submit(payload: CreatePayload) {
+    const ok = await actions.create(payload);
+    if (ok) setCreating(false);
+    return ok;
+  }
+
+  return (
+    <>
+      <Head title={t(keys.api_tokens.admin.title)} />
+      <PageShell
+        title={t(keys.api_tokens.admin.title)}
+        description={t(keys.api_tokens.admin.description)}
+        actions={
+          <Button onClick={() => setCreating(true)} disabled={props.tenant_required}>
+            <Plus className="size-4" />
+            {t(keys.api_tokens.admin.new_service_key)}
+          </Button>
+        }
+      >
+        {props.tenant_required ? (
+          <InlineBanner
+            icon={Building2}
+            tone="warning"
+            title={t(keys.api_tokens.admin.tenant_required)}
+          />
+        ) : (
+          <TokenTable
+            tokens={props.tokens}
+            showOwner
+            highlightId={highlightId}
+            onRevoke={actions.setPendingRevoke}
+          />
+        )}
+      </PageShell>
+
+      <CreateTokenDialog
+        open={creating}
+        onOpenChange={setCreating}
+        variant="service"
+        scopes={props.scopes}
+        roles={props.roles}
+        expiryPresets={props.expiry_presets}
+        busy={actions.busy}
+        onSubmit={submit}
+      />
+      <CreatedTokenDialog token={actions.created} onClose={actions.clearCreated} />
+      <RevokeTokenDialog
+        token={actions.pendingRevoke}
+        busy={actions.busy}
+        onCancel={() => actions.setPendingRevoke(null)}
+        onConfirm={actions.confirmRevoke}
+      />
+    </>
+  );
+}
+
+Admin.layout = [AdminLayout];
+export default Admin;

api_tokens/pages/Index.tsx

@@ -0,0 +1,95 @@
+import { Head, usePage } from '@inertiajs/react';
+import { keys, useT } from '@simple-module-py/i18n';
+import { ConfirmActionDialog } from '@simple-module-py/ui/components/ConfirmActionDialog';
+import { PageShell } from '@simple-module-py/ui/components/PageShell';
+import { Button } from '@simple-module-py/ui/components/ui/button';
+import { AuthenticatedLayout } from '@simple-module-py/ui/layouts/AuthenticatedLayout';
+import { Ban, Plus } from 'lucide-react';
+import { useState } from 'react';
+import { CreatedTokenDialog } from './components/CreatedTokenDialog';
+import { CreateTokenDialog } from './components/CreateTokenDialog';
+import { RevokeTokenDialog } from './components/RevokeTokenDialog';
+import { TokenTable } from './components/TokenTable';
+import { useTokenActions } from './components/useTokenActions';
+import { type CreatePayload, type TokenFormProps, tokenStatus } from './types';
+
+/** Your own personal access tokens: list, create (secret shown once), revoke. */
+function Index() {
+  const props = usePage<{ props: TokenFormProps }>().props as unknown as TokenFormProps;
+  const { t } = useT();
+  const [creating, setCreating] = useState(false);
+  const actions = useTokenActions({
+    csrfToken: props.csrf_token,
+    createUrl: `${props.api_url}/tokens/`,
+    revokeUrl: (id) => `${props.api_url}/tokens/${id}/revoke`,
+    revokeAllUrl: `${props.api_url}/tokens/revoke-all`,
+  });
+  const hasLive = props.tokens.some((tok) => tokenStatus(tok) === 'active');
+
+  async function submit(payload: CreatePayload) {
+    const ok = await actions.create(payload);
+    if (ok) setCreating(false);
+    return ok;
+  }
+
+  return (
+    <>
+      <Head title={t(keys.api_tokens.index.title)} />
+      <PageShell
+        title={t(keys.api_tokens.index.title)}
+        description={t(keys.api_tokens.index.description)}
+        actions={
+          <div className="flex gap-2">
+            <Button
+              variant="outline"
+              onClick={() => actions.setPendingRevokeAll(true)}
+              disabled={!hasLive}
+            >
+              <Ban className="size-4" />
+              {t(keys.api_tokens.revoke_all.button)}
+            </Button>
+            <Button onClick={() => setCreating(true)} disabled={props.scopes.length === 0}>
+              <Plus className="size-4" />
+              {t(keys.api_tokens.form.new_token)}
+            </Button>
+          </div>
+        }
+      >
+        <p className="text-sm text-muted-foreground">{t(keys.api_tokens.index.usage)}</p>
+        <TokenTable tokens={props.tokens} onRevoke={actions.setPendingRevoke} />
+      </PageShell>
+
+      <CreateTokenDialog
+        open={creating}
+        onOpenChange={setCreating}
+        variant="personal"
+        scopes={props.scopes}
+        expiryPresets={props.expiry_presets}
+        busy={actions.busy}
+        onSubmit={submit}
+      />
+      <CreatedTokenDialog token={actions.created} onClose={actions.clearCreated} />
+      <RevokeTokenDialog
+        token={actions.pendingRevoke}
+        busy={actions.busy}
+        onCancel={() => actions.setPendingRevoke(null)}
+        onConfirm={actions.confirmRevoke}
+      />
+      <ConfirmActionDialog
+        open={actions.pendingRevokeAll}
+        onOpenChange={(open) => !open && actions.setPendingRevokeAll(false)}
+        tone="destructive"
+        icon={Ban}
+        title={t(keys.api_tokens.revoke_all.title)}
+        description={t(keys.api_tokens.revoke_all.description)}
+        confirmLabel={t(keys.api_tokens.revoke_all.confirm)}
+        cancelLabel={t(keys.api_tokens.revoke_all.cancel)}
+        busy={actions.busy}
+        onConfirm={actions.confirmRevokeAll}
+      />
+    </>
+  );
+}
+
+Index.layout = [AuthenticatedLayout];
+export default Index;

api_tokens/pages/api.ts

@@ -0,0 +1,42 @@
+/**
+ * JSON calls to the api_tokens endpoints.
+ *
+ * Plain `fetch`, not Inertia's router: creating a token must hand the page
+ * its secret as data, once, which a redirect cannot carry. Every mutation
+ * echoes the session's CSRF token (`RequiresCsrf` on the server).
+ */
+
+export interface ApiResult<T> {
+  ok: boolean;
+  data: T | null;
+  /** The server's message when it sent a plain string; null otherwise. */
+  detail: string | null;
+}
+
+export async function postJson<T>(
+  url: string,
+  csrfToken: string,
+  body?: unknown,
+): Promise<ApiResult<T>> {
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      credentials: 'same-origin',
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': csrfToken,
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  } catch {
+    return { ok: false, data: null, detail: null };
+  }
+  const json = await response.json().catch(() => null);
+  if (!response.ok) {
+    const detail = json && typeof json.detail === 'string' ? json.detail : null;
+    return { ok: false, data: null, detail };
+  }
+  return { ok: true, data: json as T, detail: null };
+}