@pidgeon-ai/issuer 0.1.1 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 A Post issuer you run yourself, inside your own network. Your own domain
 signs your AI agents' cards, sign-ins and grants, with a key that never
-leaves you, for the agents your identity provider says you have. Nothing is
+leaves you, for the agents your identity provider (Keycloak, Auth0, Okta) says you have. Nothing is
 sent to Pidgeon: not the key, not the list of agents.
 
 It is for companies that may not hand authentication to a third party. Pidgeon
@@ -32,8 +32,8 @@ with `pidgeon-issuer export <dir>` and serve it from any static host.
 
 1. **The issuer's key**, once: `pidgeon-issuer keygen acme.com`. It writes
    `pidgeon-issuer-key.json` (mode 0600). Mount it as a secret, or put the
-   seed in `PIDGEON_ISSUER_KEY`. Any `Signer` fits in its place, so a KMS or
-   an HSM needs no change to the rest.
+   seed in `PIDGEON_ISSUER_KEY`. Or keep it in AWS KMS, below. Any `Signer`
+   fits in its place, so an HSM needs no change to the rest.
 2. **Each agent's key**, on the agent's machine: `pidgeon-issuer keygen
 acme.com --out ~/.config/pidgeon/id/acme.com.json`. Give the identity
    provider the `key` line it prints; the private half stays with the agent.
@@ -73,6 +73,37 @@ rest, and its groups are what `grants` maps.
 secret is `KEYCLOAK_CLIENT_SECRET`. `examples/self-hosted-issuer` runs all of
 it in Docker.
 
+## Auth0
+
+An agent is a machine-to-machine application whose metadata names it:
+`pidgeon_key` (the agent's public key), `pidgeon_address`, and optionally
+`pidgeon_kind`, `pidgeon_groups` (comma-separated) and `pidgeon_disabled`
+(`true` to switch it off; Auth0 applications have no enabled switch). The
+issuer reads them with an application of its own authorized for the
+Management API with `read:clients` only; its secret is
+`AUTH0_CLIENT_SECRET`.
+
+```json
+"directory": { "auth0": { "tenant": "acme.eu.auth0.com", "client_id": "<the issuer's app>" } }
+```
+
+## Okta
+
+An agent is an active OAuth service app whose profile names it:
+`"profile": { "pidgeon": { "key": "…", "address": "…", "kind": "agent",
+"groups": ["refunds"] } }`. Deactivate the app to switch it off. The issuer
+reads them with a service app of its own granted `okta.apps.read` and a
+read-only admin role, signing in with Private Key JWT; its RSA or P-256
+private key is `OKTA_PRIVATE_KEY`.
+
+```json
+"directory": { "okta": { "org": "https://acme.okta.com", "client_id": "<the issuer's app>" } }
+```
+
+On Auth0 and Okta the agent authenticates to the provider with its own RSA
+or EC credential: neither accepts an Ed25519 key for that, so the one-key
+trick is Keycloak's alone.
+
 ## Sign in to a site
 
 A site lists your issuer beside Pidgeon's:
@@ -100,6 +131,56 @@ const { site } = await signInWithPidgeon(await loadIdentity('acme.com'), {
 });
 ```
 
+## The key in AWS KMS
+
+Make an Ed25519 key that never leaves KMS and name it instead of a file:
+
+```bash
+aws kms create-key --key-spec ECC_NIST_EDWARDS25519 --key-usage SIGN_VERIFY
+aws kms create-alias --alias-name alias/pidgeon-issuer --target-key-id <key id>
+```
+
+```json
+"key": { "kms": "alias/pidgeon-issuer", "region": "eu-west-1" }
+```
+
+The issuer's role needs `kms:GetPublicKey` and `kms:Sign` on that key and
+nothing else; credentials come the AWS SDK's usual way. Install
+`@aws-sdk/client-kms` beside the library (the container image has it). The
+key is read once at start: an alias is pinned to the key it names then, and
+every signature is checked against that key before it leaves.
+
+## A person signs in, through your identity provider
+
+Your staff sign in to the same sites as themselves, through your own OpenID
+Connect provider (Keycloak, Auth0, Okta, Entra), with the flow Pidgeon Cloud
+uses. Register the issuer at the provider as a confidential client whose
+redirect URI is `https://post.acme.com/api/post/oidc/callback`, then:
+
+```json
+"person": {
+  "oidc": { "issuer": "https://sso.acme.com/realms/acme", "client_id": "pidgeon-issuer" }
+},
+"clients": [
+  {
+    "client_id": "client_shop",
+    "host": "shop.example",
+    "redirect_uris": ["https://shop.example/api/auth/pidgeon/callback"]
+  }
+]
+```
+
+with the client's secret in `PIDGEON_PERSON_CLIENT_SECRET` and a random
+`PIDGEON_ISSUER_SECRET` of 32 characters or more (`openssl rand -base64 32`),
+which seals the sign-in in progress and the sixty-second code, so there is
+still no database. The issuer will not start without it. Rotating it only
+ends the sign-ins in flight.
+
+A site that sets `issuer: 'https://post.acme.com'` signs people in there.
+The person must have a verified address at your domain that is not an
+agent's; the site gets `kind: "person"`, your provider's `sub` and that
+address.
+
 ## What it checks before it signs anything
 
 - The token request is signed by a key your identity provider gives an
@@ -113,7 +194,7 @@ const { site } = await signInWithPidgeon(await loadIdentity('acme.com'), {
 
 ## Left out
 
-The person's sign-in, userinfo, introspection and revocation endpoints (an ID
+Userinfo, introspection and revocation endpoints (an ID
 token lasts five minutes; revoking an agent is disabling it), dynamic client
 registration, and Pidgeon's card log, which would mean sending us your agents.
 Authorization stays yours: a grant is a relation (`customer:42#refunds.issue`

package/dist/bin.js

@@ -2,7 +2,7 @@
 import {
   UsageError,
   runIssuer
-} from "./chunk-CCOFMK5K.js";
+} from "./chunk-5GZMAASA.js";
 
 // src/bin.ts
 async function main() {