@pidgeon-ai/issuer 0.2.0 → 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.
@@ -84,8 +85,8 @@ interface PersonOptions {
 
 /**
  * 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
@@ -292,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)
@@ -302,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: {
@@ -322,6 +456,26 @@ 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
@@ -347,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>;
 
 /**
@@ -373,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 PersonOptions, 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-BXZ2EI2Y.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.2.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) 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"