Metadata-Version: 2.4
Name: juntai-iam-contracts
Version: 0.2.1
Summary: Production Juntai identity, authorization, and secrets service
Author: Juntai Platform Team
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/zephytiju/JuntaiIAMContracts
Project-URL: Repository, https://github.com/zephytiju/JuntaiIAMContracts.git
Project-URL: Issues, https://github.com/zephytiju/JuntaiIAMContracts/issues
Keywords: iam,oidc,spire,jws
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography<47.0.0,>=43.0.0
Requires-Dist: fastapi<1.0.0,>=0.115.0
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: ksycopg2==2.9.1; platform_system != "Darwin"
Requires-Dist: pydantic<3.0.0,>=2.9.0
Requires-Dist: PyJWT[crypto]<3.0.0,>=2.9.0
Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0
Dynamic: license-file

# Juntai IAM and Secrets

This repository contains the production identity, authorization, and secrets
service used by local and cloud Juntai profiles. The same Python artifact owns
the HTTP API, native KES migration, metadata repository, Casdoor access-token
validation, Kubernetes workload TokenReview, deny-by-default authorization,
versioned secret references, rotation, revocation, pinning, idempotency, and the
audit hash chain.

The independently versioned Python distribution is published publicly as
[`juntai-iam-contracts`](https://pypi.org/project/juntai-iam-contracts/). Platform
services declare it as an ordinary direct project dependency:

```bash
python -m pip install "juntai-iam-contracts==0.2.1"
```

Releases are built from GitHub tags and published with PyPI Trusted Publishing;
no long-lived PyPI credential is stored in this repository.

Secret bytes are accepted only by create and rotate operations. They are written
directly to the configured secret backend and are never stored in KES, returned
by management APIs, placed in audit details, or logged. Only an authorized,
tenant/application-bound workload may call the resolve endpoint. Resolve
responses are marked `no-store`.

## Production boundaries

- Human sessions use authorization code with PKCE through the configured
  Casdoor issuer. ID tokens are not API credentials.
- Workloads use short-lived projected service-account tokens validated by the
  live Kubernetes TokenReview API.
- Every action requires an exact KES policy grant. Missing policy denies.
- KES stores secret metadata, backend references, versions, pins, revocation,
  policy, workload bindings, idempotency state, and audit events only.
- Kubernetes Secret versions are immutable. Cloud profiles provide a backend
  with the same `SecretBackend` contract and keep provider credentials outside
  application configuration.
- Startup verifies `ksycopg2==2.9.1` and rejects any database server that does
  not identify itself as KingbaseES.

## API surface

- `GET /v1/session/login`, `GET /v1/session/callback`, `POST /v1/session/logout`
- `POST/GET /v1/tenants/{tenant}/applications/{application}/secrets`
- `GET /v1/tenants/{tenant}/applications/{application}/secrets/{secret}`
- `POST .../{secret}/rotate`, `POST .../{secret}/pin`, `POST .../{secret}/revoke`
- `POST /v1/workload/secrets:resolve`
- `GET /healthz`

## Runtime

All credential-bearing inputs are file references supplied by the platform
provider. Required settings include the KES DSN file, HMAC key file,
Kubernetes service-account token and CA files, exact OIDC issuer/discovery and
audience, workload audience, and secret namespace. Browser sessions additionally
require provider-supplied Casdoor client-secret and AES-GCM key files.

```bash
juntai-iam-secrets migrate
juntai-iam-secrets grant --subject-kind human --subject <oidc-subject> \
  --tenant tenant-a --application synthetic --action secret.create
juntai-iam-secrets bind-workload \
  --subject system:serviceaccount:juntai-applications:synthetic \
  --tenant tenant-a --application synthetic
juntai-iam-secrets serve --host 0.0.0.0 --port 8080
```

The container build pins its production Python base image and locks the complete
runtime package inventory in `requirements.lock`. Merges to `main` publish an
ARM64 GHCR artifact under the exact source commit tag. Platform IaC pins that
artifact and the production-only Casdoor image by digest.

## Verification

Pure contract tests run on any supported development host:

```bash
python -m pip install -e .
python -m unittest discover -s tests
ruff check .
```

KES and workload/backend verification runs inside the packaged Linux service
artifact against the official KES release and the real local Kubernetes API.
