@pidgeon-ai/issuer 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PCN Labs OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# @pidgeon-ai/issuer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+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
+Cloud runs the same issuer for everyone else. Both speak the same protocol, so
+`@pidgeon-ai/id` (the agent's side) and `@pidgeon-ai/sign-in` (the site's)
+work with either one unchanged.
+
+```bash
+npx @pidgeon-ai/issuer keygen acme.com
+```
+
+## What runs where
+
+| Where                  | What                                                                       |
+| ---------------------- | -------------------------------------------------------------------------- |
+| Inside your network    | The issuer (`pidgeon-issuer serve`, or the container), its key, its config |
+| Your identity provider | Who the agents are: their addresses, keys and groups                       |
+| `post.<your domain>`   | The public documents: your keys, your agents' cards, OpenID discovery      |
+| `_post.<your domain>`  | A TXT record, so verifiers find `post.<your domain>`                       |
+| Each agent             | Its own Ed25519 key, which signs its mail, its requests and its sign-ins   |
+
+The token endpoint only needs to reach your agents. Everything a stranger
+reads is a document: publish it through your reverse proxy, or write it out
+with `pidgeon-issuer export <dir>` and serve it from any static host.
+
+## Run it
+
+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.
+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.
+3. **`issuer.json`**: copy `issuer.example.json`. `directory.keycloak` reads
+   the agents from Keycloak (below); `directory.static` lists them by hand. `grants` maps a group to what its agents may do, signed by
+   your domain as the organisation. `clients` are the sites you let your
+   agents sign in to.
+4. **DNS**: `pidgeon-issuer dns` prints the `_post` record and where
+   `post.acme.com` must answer.
+5. **Serve**: `pidgeon-issuer serve` (port `PORT`, default 8080), or
+   `docker build -f packages/issuer/Dockerfile -t pidgeon-issuer .` from this
+   repository's root and run it with the config and the key mounted at
+   `/etc/pidgeon-issuer/`.
+
+## Keycloak
+
+An agent is a Keycloak client with a service account, in the `agents` group.
+Its key is the Ed25519 key Keycloak authenticates it with (Credentials →
+Signed JWT, EdDSA), so the agent holds one key for Keycloak and for sites; a
+client on a secret names its key in a `pidgeon.key` attribute instead.
+`pidgeon.address` (default `<clientId>@<domain>`) and `pidgeon.kind` say the
+rest, and its groups are what `grants` maps.
+
+```json
+"directory": {
+  "keycloak": {
+    "url": "https://sso.acme.internal",
+    "realm": "acme",
+    "client_id": "pidgeon-issuer",
+    "group": "agents"
+  }
+}
+```
+
+`pidgeon-issuer` is a client of its own with a service account holding
+`realm-management`'s `view-clients` and `view-users`, nothing that writes; its
+secret is `KEYCLOAK_CLIENT_SECRET`. `examples/self-hosted-issuer` runs all of
+it in Docker.
+
+## Sign in to a site
+
+A site lists your issuer beside Pidgeon's:
+
+```ts
+import { pidgeonSignIn } from '@pidgeon-ai/sign-in';
+
+export const pidgeon = pidgeonSignIn({
+  clientId: 'client_shop',
+  url: 'https://shop.example',
+  secret: process.env.PIDGEON_SESSION_SECRET!,
+  issuers: ['https://post.acme.com'],
+});
+```
+
+and your agent signs in as it would through Pidgeon Cloud: its card comes from
+`post.acme.com`, and it goes to the issuer that signed the card.
+
+```ts
+import { loadIdentity, signInWithPidgeon } from '@pidgeon-ai/id';
+
+const { site } = await signInWithPidgeon(await loadIdentity('acme.com'), {
+  agent: 'support-agent@acme.com',
+  site: 'https://shop.example/api/auth/pidgeon/token',
+});
+```
+
+## What it checks before it signs anything
+
+- The token request is signed by a key your identity provider gives an
+  agent, covers what it must, and is used once (one replica, or pass a
+  shared `replay` store).
+- The card is one this issuer signed, current, that agent's, naming that key.
+- The agent is live in the identity provider **now**: disable it there and
+  its next sign-in fails.
+- A grant is one this issuer signed, that agent's, still held through its
+  group, and for that site.
+
+## Left out
+
+The person's sign-in, 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`
+for an agent), so it can be written from the engine you already run.
+
+Apache-2.0.

package/dist/bin.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import {
+  UsageError,
+  runIssuer
+} from "./chunk-CCOFMK5K.js";
+
+// src/bin.ts
+async function main() {
+  try {
+    process.stdout.write(
+      `${await runIssuer(process.argv.slice(2), process.env, {
+        log: (line) => process.stderr.write(`${line}
+`)
+      })}
+`
+    );
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : "Something went wrong."}
+`);
+    process.exit(error instanceof UsageError ? 2 : 1);
+  }
+}
+void main();
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["import { runIssuer, UsageError } from './cli';\n\n/** `pidgeon-issuer <command>`. Nothing else in this package runs anything on import. */\nasync function main() {\n  try {\n    process.stdout.write(\n      `${await runIssuer(process.argv.slice(2), process.env, {\n        log: (line) => process.stderr.write(`${line}\\n`),\n      })}\\n`,\n    );\n  } catch (error) {\n    process.stderr.write(`${error instanceof Error ? error.message : 'Something went wrong.'}\\n`);\n    process.exit(error instanceof UsageError ? 2 : 1);\n  }\n}\n\nvoid main();\n"],"mappings":";;;;;;;AAGA,eAAe,OAAO;AACpB,MAAI;AACF,YAAQ,OAAO;AAAA,MACb,GAAG,MAAM,UAAU,QAAQ,KAAK,MAAM,CAAC,GAAG,QAAQ,KAAK;AAAA,QACrD,KAAK,CAAC,SAAS,QAAQ,OAAO,MAAM,GAAG,IAAI;AAAA,CAAI;AAAA,MACjD,CAAC,CAAC;AAAA;AAAA,IACJ;AAAA,EACF,SAAS,OAAO;AACd,YAAQ,OAAO,MAAM,GAAG,iBAAiB,QAAQ,MAAM,UAAU,uBAAuB;AAAA,CAAI;AAC5F,YAAQ,KAAK,iBAAiB,aAAa,IAAI,CAAC;AAAA,EAClD;AACF;AAEA,KAAK,KAAK;","names":[]}