@pidgeon-ai/issuer 0.1.1 → 0.4.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
+import { KeyObject } from 'node:crypto';
 import { Server } from 'node:http';
 
 /**
  * Who the agents are. The issuer holds no list of its own: the company's
- * identity provider is the record (Keycloak first; `keycloak.ts`), read
+ * identity provider is the record (`keycloak.ts`, `auth0.ts`, `okta.ts`), read
  * through this interface, and the issuer turns what it says into cards,
  * keys in the policy, and grants. Pidgeon is the format and the check,
  * never the identity provider.
@@ -42,10 +43,50 @@ declare function staticDirectory(agents: DirectoryAgent[]): Directory;
  */
 declare function cachedDirectory(inner: Directory, seconds?: number, now?: () => number): Directory;
 
+/**
+ * A person signs in at the issuer: Pidgeon Cloud's person flow, with the
+ * company's own identity provider where Cloud has its consent page.
+ *
+ * The site speaks to the issuer exactly as it speaks to Cloud (the
+ * authorization code flow with PKCE and a nonce, `@pidgeon-ai/sign-in`'s
+ * `login` and `callback`). The issuer is a relying party of the company's
+ * OpenID Connect provider (Keycloak, Auth0, Okta, Entra): it sends the
+ * browser there with its own PKCE, state and nonce, checks the ID token
+ * that comes back, and signs the person in to the site as `kind: person`
+ * with the provider's `sub` and a verified address at the domain.
+ *
+ * **No database.** What a store would hold travels sealed (AES-256-GCM
+ * under `PIDGEON_ISSUER_SECRET`): the sign-in in progress in an HttpOnly
+ * cookie on the issuer's host, bound to the browser that started it; the
+ * code, sixty seconds, used once through the issuer's replay store.
+ * Rotating the secret ends the sign-ins in flight, and nothing else.
+ */
+/** The company's identity provider, as its relying party. */
+interface PersonOptions {
+    /** At least 32 characters. Seals the sign-in in progress and the code. */
+    secret: string;
+    oidc: {
+        /** The provider's issuer, exactly as its ID tokens say: `https://sso.acme.com/realms/acme`. */
+        issuer: string;
+        /**
+         * Where the issuer fetches the provider's configuration, when it reaches
+         * the provider by another name than browsers do. Default
+         * `<issuer>/.well-known/openid-configuration`.
+         */
+        discoveryUrl?: string;
+        clientId: string;
+        clientSecret: string;
+        /** How the issuer authenticates at the provider's token endpoint. Default `client_secret_basic`. */
+        tokenAuth?: 'client_secret_basic' | 'client_secret_post';
+    };
+    /** Domains a person's verified address may be at. Default the issuer's domain. */
+    emailDomains?: string[];
+}
+
 /**
  * The issuer's signing key, behind one interface so custody never touches
- * the protocol: a file today; AWS KMS or an HSM over PKCS#11 implement the
- * same three members and nothing else changes.
+ * the protocol: a file, AWS KMS (`kms.ts`), or an HSM over PKCS#11
+ * implementing the same three members, and nothing else changes.
  *
  * Everything the issuer signs is a JWS signing input (a card, an ID token,
  * a grant), a few hundred bytes, so a KMS that signs pure Ed25519 only up to
@@ -88,7 +129,9 @@ declare function seedSigner(seed: string, options?: {
  * work against it unchanged: the policy and the card at `post.<domain>`
  * (the draft's §discovery and §card), the token exchange an agent signs
  * (RFC 8693, Web Bot Auth's profile) and the ID token a site checks
- * (`@pidgeon-ai/sign-in`), grants (§grants). The formats are the app's own
+ * (`@pidgeon-ai/sign-in`), grants (§grants), and a person's sign-in, the
+ * authorization code flow with PKCE, through the company's own identity
+ * provider (`person.ts`). The formats are the app's own
  * (`src/lib/post/card.ts`, `grant.ts`, `pidgeon-sign-in.ts`), written out
  * here because a package cannot import the app; `tests/unit/issuer.test.ts`
  * holds them equal by reading what this signs with the app's own readers.
@@ -97,7 +140,7 @@ declare function seedSigner(seed: string, options?: {
  * used once through `replay`, in memory unless a shared store is passed.
  * Run one replica, or pass one.
  *
- * Left out on purpose: the person's flow, userinfo, introspection and
+ * Left out on purpose: userinfo, introspection and
  * revocation (each needs a store; an ID token lives five minutes and
  * revoking an agent is disabling it in the identity provider), dynamic
  * client registration, and the card log.
@@ -110,6 +153,9 @@ declare const PATHS: {
     readonly card: "/.well-known/post/card";
     readonly directory: "/.well-known/http-message-signatures-directory";
     readonly token: "/api/post/oidc/token";
+    readonly authorize: "/api/post/oidc/authorize";
+    /** The issuer's own: where the company's identity provider sends a person back. Cloud has none. */
+    readonly callback: "/api/post/oidc/callback";
     readonly jwks: "/api/post/oidc/jwks";
     readonly grants: "/api/post/grants";
 };
@@ -133,10 +179,14 @@ interface GrantRule {
     /** How long each signed copy lasts. Default 30. */
     days?: number;
 }
-/** A site, registered by hand: its `client_id` and the host its grants must be for. */
+/**
+ * A site, registered by hand: its `client_id`, the host its grants must be
+ * for, and where a person's sign-in may return to, each matched exactly.
+ */
 interface StaticClient {
     client_id: string;
     host: string;
+    redirect_uris?: string[];
 }
 /** Remembers a signature's `keyid nonce` until it expires; false when it was used. */
 interface ReplayStore {
@@ -162,6 +212,8 @@ interface IssuerOptions {
      * make it fetch an arbitrary URL.
      */
     clientMetadataHosts?: string[];
+    /** A person's sign-in, through the company's identity provider. Absent: agents only. */
+    person?: PersonOptions;
     replay?: ReplayStore;
     fetch?: typeof fetch;
     /** Milliseconds since the epoch, for tests. */
@@ -241,6 +293,135 @@ interface KeycloakOptions {
 }
 declare function keycloakDirectory(options: KeycloakOptions): Directory;
 
+/**
+ * Auth0 as the directory: the issuer reads the tenant's Management API and
+ * never writes it.
+ *
+ * **An agent is a machine-to-machine application** (`app_type:
+ * non_interactive`) whose `client_metadata` says so. Auth0 metadata keys
+ * cannot hold a dot, so the names are Keycloak's with an underscore:
+ *
+ * | `client_metadata`  | Becomes                                                       |
+ * | ------------------ | ------------------------------------------------------------- |
+ * | `pidgeon_key`      | the agent's Ed25519 public key (`x`, base64url); required     |
+ * | `pidgeon_address`  | its address, at the issuer's domain; required                 |
+ * | `pidgeon_kind`     | `agent` (default) or `service`                                |
+ * | `pidgeon_groups`   | comma-separated, what the config's `grants` map               |
+ * | `pidgeon_disabled` | `true`: not an agent, from its next sign-in                    |
+ *
+ * **Disabling.** An Auth0 application has no enabled switch, so an agent
+ * is disabled with `pidgeon_disabled` or by deleting the application.
+ * Whoever holds `update:clients` can set or clear it, so it is exactly as
+ * strong as that permission, the same people who could change its key.
+ *
+ * **One key, two uses is not possible here.** Auth0's Private Key JWT takes
+ * RS256, RS384 and PS256 with RSA keys only, not Ed25519, so the agent
+ * authenticates to Auth0 some other way and names its Pidgeon key in
+ * `pidgeon_key`.
+ *
+ * The card's `sub` is the `client_id`, which Auth0 generates and never lets
+ * anyone change; its documentation does not say whether a deleted
+ * application's id can come back. `created_at` is the application's.
+ *
+ * **The issuer's own credential** is a machine-to-machine application
+ * authorized for the Management API with `read:clients` only: never
+ * `read:client_keys` or `read:client_credentials`, which expose secrets.
+ * Its secret comes from the environment.
+ */
+interface Auth0Options {
+    /** The tenant's domain: `acme.eu.auth0.com`, or its custom domain. */
+    tenant: string;
+    /** The issuer's own application. */
+    clientId: string;
+    clientSecret: string;
+    /** The domain agents' addresses are at. */
+    domain: string;
+    fetch?: typeof fetch;
+    /** Milliseconds since the epoch, for tests. */
+    now?: () => number;
+}
+declare function auth0Directory(options: Auth0Options): Directory;
+
+/**
+ * Okta as the directory: the issuer reads the org's Apps API and never
+ * writes it.
+ *
+ * **An agent is an active OAuth 2.0 service app** (`application_type:
+ * service`, client credentials) whose `profile` names it. An Okta group
+ * holds people, never apps, so the agent's groups live in the profile too,
+ * as Okta's own `profile.groupallowlist` pattern does:
+ *
+ * ```json
+ * "profile": { "pidgeon": { "key": "<x>", "address": "support@acme.com", "kind": "agent", "groups": ["refunds"] } }
+ * ```
+ *
+ * A deactivated app (`status: INACTIVE`) or a deleted one is not an agent
+ * from its next sign-in. The card's `sub` is the app's id; `created_at` is
+ * the app's `created`.
+ *
+ * **One key, two uses is not possible here.** An Okta app's JWKS takes RSA
+ * and EC keys only, not Ed25519, so the agent authenticates to Okta with
+ * another key and names its Pidgeon key in the profile.
+ *
+ * **The issuer's own credential** is a service app of its own, granted the
+ * `okta.apps.read` scope and a read-only admin role (Okta requires both).
+ * Okta takes only Private Key JWT for its own scopes, so the issuer signs a
+ * client assertion with an RSA or P-256 key whose public half is in that
+ * app's JWKS; the private half comes from the environment.
+ */
+interface OktaOptions {
+    /** The org: `https://acme.okta.com`. */
+    org: string;
+    /** The issuer's own service app. */
+    clientId: string;
+    /** Its RSA or P-256 private key, PEM, for the client assertion. */
+    privateKey: string | KeyObject;
+    /** That key's `kid` in the app's JWKS, when the app has more than one. */
+    keyId?: string;
+    /** The domain agents' addresses are at. */
+    domain: string;
+    fetch?: typeof fetch;
+    /** Milliseconds since the epoch, for tests. */
+    now?: () => number;
+}
+declare function oktaDirectory(options: OktaOptions): Directory;
+
+/** The two KMS calls the issuer makes, as `@aws-sdk/client-kms` shapes them. */
+interface KmsApi {
+    getPublicKey(input: {
+        KeyId: string;
+    }): Promise<{
+        KeyId?: string;
+        KeySpec?: string;
+        KeyUsage?: string;
+        SigningAlgorithms?: string[];
+        PublicKey?: Uint8Array;
+    }>;
+    sign(input: {
+        KeyId: string;
+        Message: Uint8Array;
+        MessageType: 'RAW';
+        SigningAlgorithm: string;
+    }): Promise<{
+        KeyId?: string;
+        Signature?: Uint8Array;
+    }>;
+}
+interface KmsSignerOptions {
+    /** The key's ARN, id, or an alias (`alias/pidgeon-issuer`), resolved once at start. */
+    keyId: string;
+    /** Default the SDK's: `AWS_REGION`, then the profile's. */
+    region?: string;
+    kms?: KmsApi;
+}
+declare function kmsSigner(options: KmsSignerOptions): Promise<Signer & {
+    keyArn: string;
+}>;
+/** A key in KMS the issuer no longer signs with, published until `notAfter`: its public half only. */
+declare function kmsRetiredKey(options: KmsSignerOptions & {
+    notAfter: Date;
+}): Promise<RetiredKey>;
+
 /**
  * `issuer.json`, the one file a company writes (`issuer.example.json`).
  * Secrets never go in it: the key is a file it names (mounted as a secret)
@@ -251,11 +432,15 @@ interface IssuerFile {
     domain: string;
     issuer?: string;
     organisation?: string;
-    /** The key file, relative to this file. `PIDGEON_ISSUER_KEY` (the seed) wins when set. */
-    key?: string;
+    /**
+     * The key file, relative to this file, or a key in AWS KMS (`{ "kms":
+     * "arn:aws:kms:…" }`, an `ECC_NIST_EDWARDS25519` key). `PIDGEON_ISSUER_KEY`
+     * (the seed) wins when set.
+     */
+    key?: KeyRef;
     /** Keys being withdrawn: published until `not_after`. */
     retired?: {
-        key: string;
+        key: KeyRef;
         not_after: string;
     }[];
     directory: {
@@ -271,6 +456,44 @@ interface IssuerFile {
             /** The group whose members are agents. Default `agents`. */
             group?: string;
         };
+    } | {
+        auth0: {
+            /** The tenant's domain: `acme.eu.auth0.com`. */
+            tenant: string;
+            /** The issuer's own machine-to-machine application, with `read:clients` only. */
+            client_id: string;
+            /** The environment variable holding its secret. Default `AUTH0_CLIENT_SECRET`. */
+            client_secret_env?: string;
+        };
+    } | {
+        okta: {
+            /** The org: `https://acme.okta.com`. */
+            org: string;
+            /** The issuer's own service app, with `okta.apps.read` and a read-only admin role. */
+            client_id: string;
+            /** The environment variable holding its RSA or P-256 private key, PEM. Default `OKTA_PRIVATE_KEY`. */
+            private_key_env?: string;
+            /** That key's `kid` in the app's JWKS. */
+            key_id?: string;
+        };
+    };
+    /**
+     * A person's sign-in, through the company's OpenID Connect provider, with
+     * the issuer as one of its clients. Needs `PIDGEON_ISSUER_SECRET`.
+     */
+    person?: {
+        oidc: {
+            /** The provider's issuer, as its ID tokens say. */
+            issuer: string;
+            /** Where the issuer reaches the provider's configuration, when not at its issuer URL. */
+            discovery_url?: string;
+            client_id: string;
+            /** The environment variable holding its secret. Default `PIDGEON_PERSON_CLIENT_SECRET`. */
+            client_secret_env?: string;
+            token_auth?: 'client_secret_basic' | 'client_secret_post';
+        };
+        /** Default the domain. */
+        email_domains?: string[];
     };
     grants?: GrantRule[];
     clients?: StaticClient[];
@@ -278,6 +501,11 @@ interface IssuerFile {
     /** How long the list of agents is held for the public reads, in seconds. Default 60. */
     directory_cache_seconds?: number;
 }
+/** A key file's path, or a KMS key: its ARN, id or alias, and its region when not the default. */
+type KeyRef = string | {
+    kms: string;
+    region?: string;
+};
 declare function loadConfig(path: string, env?: Record<string, string | undefined>): Promise<IssuerOptions>;
 
 /**
@@ -304,4 +532,4 @@ declare function runIssuer(args: string[], env?: Record<string, string | undefin
     log?: (line: string) => void;
 }): Promise<string>;
 
-export { type Directory, type DirectoryAgent, type GrantRule, type Issuer, type IssuerFile, type IssuerOptions, type KeycloakOptions, PATHS, type ReplayStore, type RetiredKey, type Signer, type StaticClient, TOKEN_EXCHANGE, UsageError, cachedDirectory, createIssuer, fileSigner, keycloakDirectory, loadConfig, memoryReplayStore, runIssuer, seedSigner, serve, staticDirectory };
+export { type Auth0Options, type Directory, type DirectoryAgent, type GrantRule, type Issuer, type IssuerFile, type IssuerOptions, type KeyRef, type KeycloakOptions, type KmsApi, type KmsSignerOptions, type OktaOptions, PATHS, type PersonOptions, type ReplayStore, type RetiredKey, type Signer, type StaticClient, TOKEN_EXCHANGE, UsageError, auth0Directory, cachedDirectory, createIssuer, fileSigner, keycloakDirectory, kmsRetiredKey, kmsSigner, loadConfig, memoryReplayStore, oktaDirectory, runIssuer, seedSigner, serve, staticDirectory };

package/dist/index.js

@@ -3,27 +3,35 @@ import {
   PATHS,
   TOKEN_EXCHANGE,
   UsageError,
+  auth0Directory,
   cachedDirectory,
   createIssuer,
   fileSigner,
   keycloakDirectory,
+  kmsRetiredKey,
+  kmsSigner,
   loadConfig,
   memoryReplayStore,
+  oktaDirectory,
   runIssuer,
   seedSigner,
   serve,
   staticDirectory
-} from "./chunk-CCOFMK5K.js";
+} from "./chunk-5GZMAASA.js";
 export {
   PATHS,
   TOKEN_EXCHANGE,
   UsageError,
+  auth0Directory,
   cachedDirectory,
   createIssuer,
   fileSigner,
   keycloakDirectory,
+  kmsRetiredKey,
+  kmsSigner,
   loadConfig,
   memoryReplayStore,
+  oktaDirectory,
   runIssuer,
   seedSigner,
   serve,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pidgeon-ai/issuer",
-  "version": "0.1.1",
-  "description": "A Post issuer you run yourself, inside your own network: your domain signs your AI agents' cards and sign-ins with a key that never leaves it, for the agents your identity provider (Keycloak) says you have.",
+  "version": "0.4.0",
+  "description": "A Post issuer you run yourself, inside your own network: your domain signs your AI agents' cards and sign-ins with a key that never leaves it, for the agents your identity provider (Keycloak, Auth0, Okta) says you have.",
   "keywords": [
     "agent-identity",
     "ai-agents",
@@ -9,6 +9,8 @@
     "openid-connect",
     "token-exchange",
     "keycloak",
+    "auth0",
+    "okta",
     "web-bot-auth",
     "pidgeon",
     "post"
@@ -43,7 +45,16 @@
   "publishConfig": {
     "access": "public"
   },
+  "peerDependencies": {
+    "@aws-sdk/client-kms": "^3.1164.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-kms": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@aws-sdk/client-kms": "^3.1164.0",
     "tsup": "^8.5.0",
     "typescript": "^5",
     "@pidgeon-ai/id": "0.2.0"