@pidgeon-ai/issuer 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -42,6 +42,46 @@ 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
@@ -88,7 +128,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 +139,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 +152,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 +178,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 +211,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. */
@@ -272,6 +323,24 @@ interface IssuerFile {
             group?: 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[];
     client_metadata_hosts?: string[];
@@ -304,4 +373,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 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 };

package/dist/index.js

@@ -13,7 +13,7 @@ import {
   seedSigner,
   serve,
   staticDirectory
-} from "./chunk-CCOFMK5K.js";
+} from "./chunk-BXZ2EI2Y.js";
 export {
   PATHS,
   TOKEN_EXCHANGE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pidgeon-ai/issuer",
-  "version": "0.1.1",
+  "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.",
   "keywords": [
     "agent-identity",