Metadata-Version: 2.4
Name: sanoptis-auth
Version: 0.5.2
Summary: Microsoft SSO + admin-broker credential client for Sanoptis Claude Code plugins.
Project-URL: Homepage, https://github.com/Sanoptis-BI/sanoptis-auth
Project-URL: Repository, https://github.com/Sanoptis-BI/sanoptis-auth
Project-URL: Issues, https://github.com/Sanoptis-BI/sanoptis-auth/issues
Author-email: Sanoptis-BI <data-ai@sanoptis.com>
License: Copyright (c) 2026 Sanoptis AG
        
        # PolyForm Internal Use License 1.0.0
        
        <https://polyformproject.org/licenses/internal-use/1.0.0>
        
        ## Acceptance
        
        In order to get any license under these terms, you must agree
        to them as both strict obligations and conditions to all
        your licenses.
        
        ## Copyright License
        
        The licensor grants you a copyright license for the
        software to do everything you might do with the software
        that would otherwise infringe the licensor's copyright in
        it for any permitted purpose.  However, you may only make
        changes or new works based on the software according to
        [Changes and New Works License](#changes-and-new-works-license),
        and you may not distribute the software.
        
        ## Internal Business Use
        
        Use of the software for the internal business operations
        of you and your company is use for a permitted purpose.
        
        ## Changes and New Works License
        
        The licensor grants you an additional copyright license
        to make changes and new works based on the software for
        any permitted purpose.
        
        ## Patent License
        
        The licensor grants you a patent license for the software
        that covers patent claims the licensor can license, or
        becomes able to license, that you would infringe by using
        the software.
        
        ## Fair Use
        
        You may have "fair use" rights for the software under the
        law. These terms do not limit them.
        
        ## No Other Rights
        
        These terms do not allow you to sublicense or transfer any
        of your licenses to anyone else, or prevent the licensor
        from granting licenses to anyone else. These terms do not
        imply any other licenses.
        
        ## Patent Defense
        
        If you make any written claim that the software infringes
        or contributes to infringement of any patent, your patent
        license for the software granted under these terms ends
        immediately. If your company makes such a claim, your
        patent license ends immediately for work on behalf of your
        company.
        
        ## Violations
        
        The first time you are notified in writing that you have
        violated any of these terms, or done anything with the
        software not covered by your licenses, your licenses can
        nonetheless continue if you come into full compliance
        with these terms, and take practical steps to correct past
        violations, within 32 days of receiving notice.  Otherwise,
        all your licenses end immediately.
        
        ## No Liability
        
        ***As far as the law allows, the software comes as is,
        without any warranty or condition, and the licensor
        will not be liable to you for any damages arising out of
        these terms or the use or nature of the software, under
        any kind of legal claim.***
        
        ## Definitions
        
        The **licensor** is the individual or entity offering these
        terms, and the **software** is the software the licensor makes
        available under these terms.
        
        **You** refers to the individual or entity agreeing to these
        terms.
        
        **Your company** is any legal entity, sole proprietorship,
        or other kind of organization that you work for, plus all
        organizations that have control over, are under the control
        of, or are under common control with that organization.
        **Control** means ownership of substantially all the assets of
        an entity, or the power to direct its management and policies
        by vote, contract, or otherwise.  Control can be direct or
        indirect.
        
        **Your licenses** are all the licenses granted to you for the
        software under these terms.
        
        **Use** means anything you do with the software requiring one
        of your licenses.
License-File: LICENSE
Keywords: azure,claude-code,key-vault,msal,plugin,sanoptis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.13,>=3.11
Requires-Dist: azure-identity<2,>=1.19
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: mcp<2,>=1.0
Requires-Dist: msal-extensions<2,>=1.2
Requires-Dist: pydantic<3,>=2
Provides-Extra: admin
Requires-Dist: alembic<2,>=1.13; extra == 'admin'
Requires-Dist: azure-identity<2,>=1.17; extra == 'admin'
Requires-Dist: azure-keyvault-secrets<5,>=4.8; extra == 'admin'
Requires-Dist: cryptography<45,>=42; extra == 'admin'
Requires-Dist: email-validator<3,>=2.0; extra == 'admin'
Requires-Dist: fastapi<0.120,>=0.115; extra == 'admin'
Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'admin'
Requires-Dist: pyjwt[crypto]<3,>=2.8; extra == 'admin'
Requires-Dist: python-dotenv<2,>=1.0; extra == 'admin'
Requires-Dist: pyyaml<7,>=6.0; extra == 'admin'
Requires-Dist: reflex<0.9,>=0.8.28; extra == 'admin'
Requires-Dist: sqlmodel<0.1,>=0.0.22; extra == 'admin'
Description-Content-Type: text/markdown

# sanoptis-auth

Microsoft SSO + Postgres-broker credential management for Sanoptis Claude Code plugins.

A single library that any Sanoptis plugin can use to fetch its API secrets, gated by the user's normal Microsoft sign-in. No per-plugin dotfiles, no `chmod` gymnastics, no hand-rolled credential bootstrap docs.

## Install

```shell
pip install sanoptis-auth
```

## What it does

- **Fetches secrets** from the Sanoptis admin broker (a Reflex/FastAPI app with a Postgres backend that stores Fernet-encrypted secret values).
- **Authenticates the user** via Microsoft SSO on first use: reuses an existing `az login` session if present, otherwise opens a browser tab for one-click sign-in. Refresh token cached in the OS-native secure store (DPAPI/Keychain/libsecret) for ~90 days.
- **Enforces access policy** at the broker, per-plugin:
  - `public` plugins — any authenticated Sanoptis user may read.
  - `restricted` plugins — only users added as members (in the admin UI) may read.

## Use it in a plugin

Add to your plugin's `requirements.txt`:

```
sanoptis-auth>=0.5.0,<0.6
```

Replace any per-plugin credential loading with:

```python
from sanoptis_auth import get_secret

api_key = get_secret("yokoy/api-key")
api_secret = get_secret("yokoy/api-secret")
```

**Do not** register the `sanoptis-auth` MCP server in your own plugin's `.mcp.json`. The separate `sanoptis-auth` plugin in the Sanoptis marketplace registers it once for every Claude Code session; your plugin just imports the Python library.

## First-time login (end user)

1. Install the plugin in Claude Code.
2. Use any tool that needs a secret. If no MSAL cache exists, Claude will call `start_sanoptis_login` for you (or you can call it directly).
3. A browser tab opens at the Microsoft sign-in page. If your browser already holds an M365 cookie (the typical case inside Sanoptis), the redirect is instant.
4. Done — the next ~90 days of plugin usage are automatic.

Headless environments (SSH, Docker, CI) have no browser, so the SDK's credential chain falls through to an explicit error pointing at `az login`. Run `az login --tenant <tenant-id>` once and the `AzureCliCredential` step picks it up on the next call.

## Local dev override

For working offline or before your admin-broker membership is set up:

```shell
export SANOPTIS_AUTH_LOCAL_OVERRIDE_FILE=~/.sanoptis-auth-overrides.env
cat > ~/.sanoptis-auth-overrides.env <<'EOF'
yokoy/api-key=dev-key
yokoy/api-secret=dev-secret
EOF
chmod 600 ~/.sanoptis-auth-overrides.env
```

`get_secret()` checks this file first when the env var is set.

## Admin app

The `sanoptis_admin/` package is a Reflex web app that is the primary tool for managing plugins, secrets, and memberships. Admins sign in with their Sanoptis Microsoft account and can:

- **Create plugins** — adds a row to the admin DB and auto-enrols the creator as first member.
- **Add/rotate/delete secrets** — Fernet-encrypts the plaintext and stores the ciphertext in Postgres.
- **Manage members** — add/remove users (by UPN) from a plugin's membership set.
- **Flip access policy** — per-plugin, between `public` and `restricted`.
- **Audit** — every mutation and every successful secret read is logged with actor UPN, action, and target.

All operations run under the admin's own delegated token — no elevated service principal, no app-permission scopes. Non-admins (absent from `ADMIN_UPNS`) see a "Not authorized" page.

Deployed to Azure Container Apps via `infra/azure/admin_app.tf`. Container image built and pushed by `.github/workflows/deploy-admin.yml` on pushes to `main` that touch `sanoptis_admin/**`.

Local dev:

```bash
cd sanoptis_admin
SANOPTIS_ADMIN_CONFIG=$(pwd)/web.yaml \
DATABASE_URL=sqlite:///admin.db \
ENTRA_CLIENT_SECRET=... \
SESSION_SECRET=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") \
DATA_ENCRYPTION_KEY=$(python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())") \
ADMIN_UPNS=you@sanoptis.com \
pixi run -e admin reflex run
```

See `sanoptis_admin/web.yaml.example` for the config schema.

## Adding a new secret to a plugin

Preferred: use the admin app — "Add/rotate secret" writes to Postgres under the admin's own identity and records the rotation in the audit log.

Break-glass: the `gha` service principal has `Key Vault Secrets Officer` on the shared KV (see `infra/entra/gha_app.tf`) which lets an operator rotate container-level secrets (DATA_ENCRYPTION_KEY etc.) — but plugin secrets live in Postgres, not KV, so the admin app is the only route for those.

## Adding a new plugin

Preferred: use the admin app — "Create plugin" registers it and auto-enrols you as first member. "Add secret" then creates each secret and (for `restricted` plugins) "Add member" grants access.

In your plugin's code, unchanged from above:

```python
get_secret("myplugin/api-key")
```

## Repo layout

| Path | Purpose |
|---|---|
| `sanoptis_auth/` | Python package: azure-identity chain + admin-broker client (consumed by plugins) |
| `sanoptis_auth/mcp_server/` | stdio MCP server exposing `start_sanoptis_login` and `whoami` |
| `sanoptis_admin/` | Reflex admin web app: plugins, secrets, memberships, audit log, `/api/secrets/*` broker |
| `tests/` | pytest — `tests/` for the SDK, `sanoptis_admin/tests/` for the admin app |
| `infra/azure/` | CI-managed Terraform: Key Vault, Container App, Postgres, ACR |
| `infra/entra/` | Operator-managed Terraform: plugin public-client app, admin confidential app, GHA OIDC SP |
| `.github/workflows/` | CI, release, terraform plan/apply, admin-app deploy |

## Architecture decisions

- **Postgres broker over direct KV.** Plugin users never touch Key Vault. The admin app owns memberships + audit; KV is used only for container-level secrets (Fernet DEK, OAuth client secret, session key, admin UPN list, DB DSN).
- **Public client (no client secret) for the plugin app.** The plugin Entra app uses delegated access — tokens are minted on behalf of the signed-in user via the browser popup. Nothing to leak or rotate at the app level.
- **Per-user MSAL cache.** Token cache lives in `${CLAUDE_PLUGIN_DATA}/msal_cache.bin` when running inside a Claude Code plugin, otherwise `~/.sanoptis-auth/msal_cache.bin`. Shared across all plugins on the same user account — one sign-in, many plugins.
- **No device-code fallback.** Headless environments use `az login --tenant <tenant>` beforehand; AzureCliCredential then produces tokens silently. This keeps the chain predictable and never blocks on an invisible prompt.
- **Entra for sign-in only.** No Graph group lookups, no per-secret KV RBAC, no ARM role assignments at plugin lifecycle time. Membership lives in the admin's own Postgres.
- **Terraform over Bicep.** Reviewable, multi-cloud-portable, standard Sanoptis-BI infra tool. Runs via OIDC federated identity in CI — no stored service principal secret.

## Provisioning new infrastructure

See `infra/README.md` for the one-time Azure bootstrap procedure.

## Source of truth

This repo is the only place credentials for Sanoptis Claude Code plugins should be managed. If you find a plugin reading secrets from a dotfile or environment variable, file an issue — it should be migrated to `sanoptis_auth.get_secret`.
