@ministryofmany/client 0.1.0

package/LICENSE

@@ -0,0 +1,10 @@
+This project is dual-licensed under either of:
+
+  - Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
+  - MIT license (https://opensource.org/licenses/MIT)
+
+at your option.
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in this project by you shall be dual licensed as
+above, without any additional terms or conditions.

package/README.md

@@ -0,0 +1,282 @@
+# @ministryofmany/client
+
+OIDC relying-party SDK for **Minister** — an OpenID Connect identity provider
+that lets users authenticate _and_ disclose W3C verifiable-credential "badges"
+(email-domain, age-over-N, residency, connected accounts, and more).
+
+Use this in your app to:
+
+- Run the authorization-code flow with PKCE (S256) against Minister.
+- Verify the returned `id_token` (signature, issuer, audience, nonce).
+- Extract and **signature-verify** the disclosed badges against Minister's
+  public keys, with holder-binding enforced.
+
+Three ways to integrate: run the full flow yourself (`createMinisterClient`), verify tokens/badges on a backend (`createMinisterVerifier`), or plug into Auth.js (`@ministryofmany/client/auth-js`).
+
+ESM-only. Runs on Node 20+, Deno, and edge runtimes (Vercel Edge, Cloudflare
+Workers) — it uses the Web Crypto API and `fetch`, not `node:crypto`.
+
+## Install
+
+```sh
+pnpm add @ministryofmany/client
+```
+
+`jose` and `zod` are runtime dependencies and are installed automatically.
+
+## Quick start
+
+Create one client and reuse it. `issuer` is Minister's origin.
+
+```ts
+import { createMinisterClient } from "@ministryofmany/client";
+
+export const minister = createMinisterClient({
+  issuer: "https://ministry.id",
+  clientId: process.env.MINISTER_CLIENT_ID!,
+  clientSecret: process.env.MINISTER_CLIENT_SECRET, // omit for public/PKCE-only clients
+  redirectUri: "https://yourapp.example/auth/minister/callback",
+});
+```
+
+### 1. Start — build the authorization URL and persist flow state
+
+```ts
+import type { OidcFlowState } from "@ministryofmany/client";
+
+export async function startLogin() {
+  const { verifier, challenge } = await minister.generatePkce();
+  const state = minister.randomToken();
+  const nonce = minister.randomToken();
+
+  // Ask for the badges your app needs. `openid` is required; the SDK does
+  // not add it for you. `badgeScope("age-over-21")` === "badge:age-over-21".
+  const url = await minister.getAuthorizationUrl({
+    scopes: [
+      "openid",
+      "profile",
+      minister.badgeScope("age-over-21"),
+      minister.badgeScope("email-domain"),
+    ],
+    state,
+    nonce,
+    codeChallenge: challenge,
+  });
+
+  // YOU own persistence. Store this keyed by `state`; the SDK stores nothing.
+  const flow: OidcFlowState = {
+    state,
+    nonce,
+    codeVerifier: verifier,
+    expiresAt: Date.now() + 10 * 60_000, // 10 minutes
+  };
+  await saveFlow(state, flow); // your storage: signed cookie, KV, DB row, ...
+
+  return url; // redirect the user here (302)
+}
+```
+
+> **You own the flow state, and you must consume it atomically by `state`.**
+> On callback, look the record up by the returned `state`, **delete it in the
+> same operation** (delete-on-read), and reject if it is missing or expired.
+> This makes each `state`/`nonce` usable at most once, which is what defends
+> the flow against CSRF and replay. The SDK deliberately stores nothing.
+
+### 2. Callback — exchange the code for verified claims + badges
+
+```ts
+export async function handleCallback(req: Request) {
+  const url = new URL(req.url);
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+  if (!code || !state) throw new Error("missing code/state");
+
+  // Atomic consume: fetch AND delete by state in one step.
+  const flow = await takeFlow(state);
+  if (!flow || flow.expiresAt < Date.now()) {
+    throw new Error("unknown or expired login flow");
+  }
+
+  const { claims, badges, rejected } = await minister.exchangeCode({
+    code,
+    codeVerifier: flow.codeVerifier,
+    expectedNonce: flow.nonce,
+  });
+
+  // `claims.sub` is a pairwise pseudonymous id — stable for this user at
+  // YOUR client, and different from what other RPs see.
+  // `badges` are already signature-verified and holder-bound.
+  const isAdult = badges.some((b) => b.type === "age-over-21");
+
+  // `rejected` holds any disclosed badges that failed verification (bad
+  // signature, expired, wrong issuer, ...). Login still succeeds; log/alert
+  // on these if a partner may be misconfigured.
+
+  await upsertUser({
+    ministerSub: claims.sub,
+    name: claims.name,
+    avatar: claims.picture,
+    isAdult,
+  });
+
+  // ... set your own session ...
+}
+```
+
+`exchangeCode` throws `MinisterTokenError` if the token exchange fails or the
+`id_token` signature / issuer / audience / nonce / expiry checks fail — map
+that to a `401`. A disclosed badge that fails verification is **not** fatal:
+it is dropped from `badges` and surfaced in `rejected`, and login proceeds.
+
+### Verifying a badge received out of band
+
+Badges can also reach you outside the OIDC flow (e.g. a Minister share link).
+Verify any Minister VC JWT against Minister's public keys:
+
+```ts
+import { VcVerificationError } from "@ministryofmany/client";
+
+try {
+  const badge = await minister.verifyMinisterBadge(vcJwt);
+  // badge.type    -> the badge slug, e.g. "email-domain"
+  // badge.claims  -> schema-validated claims, e.g. { domain: "example.com" }
+  // badge.subject -> the holder's stable Minister DID (== credentialSubject.id);
+  //                  NOT the id_token `sub` (that is a per-RP pairwise value)
+  // badge.raw     -> the original JWT, for storage/forwarding
+} catch (err) {
+  if (err instanceof VcVerificationError) {
+    // invalid signature, wrong issuer, bad envelope, or holder-binding mismatch
+  }
+  throw err;
+}
+```
+
+Optionally validate the claim shape against the known badge vocabulary:
+
+```ts
+import { getBadgeClaimSchema } from "@ministryofmany/client";
+
+const schema = getBadgeClaimSchema("email-domain");
+const parsed = schema?.safeParse(badge.claims);
+```
+
+## Verify on your backend (without running the flow)
+
+If your app uses an OIDC library (or another service runs the flow) and you
+just need to verify a Minister `id_token` and its badges, use the verifier —
+no flow state, no redirect handling:
+
+```ts
+import { createMinisterVerifier } from "@ministryofmany/client";
+
+const minister = createMinisterVerifier({
+  issuer: "https://ministry.id",
+  clientId: "your-client-id", // enables the id_token `aud` check (recommended)
+});
+
+const claims = await minister.verifyIdToken(idToken); // throws MinisterTokenError on a bad token
+// claims: { sub, name?, picture?, raw }
+
+const { badges, rejected } = await minister.verifyBadges(idToken);
+// badges:   [{ type: "age-over-21", claims: { threshold: 21 }, subject, raw }, ...]
+// rejected: [{ raw, error }]  (badges that failed verification; never throws per-badge)
+```
+
+`verifyBadges` accepts either a raw `id_token` string (it verifies the wrapper
+first) or an already-verified payload object (it trusts the wrapper and only
+verifies the badge VCs). The verifier caches Minister's JWKS after the first
+fetch. Pass `jwks` to inject a key in tests.
+
+## With Auth.js (next-auth)
+
+`@ministryofmany/client/auth-js` gives you a provider config and a badge helper you
+hand to Auth.js through its documented extension points. We do **not** modify,
+fork, or pin Auth.js — `@auth/core` is a types-only optional peer.
+
+```ts
+import NextAuth from "next-auth";
+import { ministerProvider, ministerBadgesFromProfile } from "@ministryofmany/client/auth-js";
+import { badgeScopes } from "@ministryofmany/client/badges";
+
+export const { handlers, auth } = NextAuth({
+  providers: [
+    ministerProvider({
+      clientId: process.env.MINISTER_CLIENT_ID!,
+      clientSecret: process.env.MINISTER_CLIENT_SECRET, // omit for public clients
+      issuer: process.env.MINISTER_ISSUER!,
+      scopes: ["openid", "profile", ...badgeScopes(["age-over-18"])],
+    }),
+  ],
+  callbacks: {
+    async jwt({ token, profile }) {
+      if (profile) {
+        const { badges } = await ministerBadgesFromProfile(profile, {
+          issuer: process.env.MINISTER_ISSUER!,
+        });
+        token.ministerBadges = badges;
+      }
+      return token;
+    },
+  },
+});
+```
+
+`ministerProvider` returns a standard OIDC provider config; Auth.js verifies the
+`id_token`, and `ministerBadgesFromProfile` verifies the nested badge VCs inside
+your own callback.
+
+### Subpath imports
+
+- `@ministryofmany/client` — the main entry: flow client, verifier, errors, types, and the badge vocabulary.
+- `@ministryofmany/client/badges` — the badge vocabulary alone (slugs, scopes, Zod claim schemas, `badgeScope`/`badgeScopes`/`badgeTypeOf`). Dependency-light; no jose pulled in. Useful for building scope lists or parsing claims in a UI.
+- `@ministryofmany/client/auth-js` — the Auth.js helpers only (`ministerProvider`, `ministerBadgesFromProfile`).
+
+## What "verified" means here
+
+- **id_token:** EdDSA signature against Minister's JWKS, plus `iss` ==
+  configured issuer, `aud` == your `clientId`, and `nonce` == the value you
+  persisted at start, with `exp`/`iat` present and `exp` not in the past.
+- **Each badge:** EdDSA signature against Minister's public keys, `iss` ==
+  `did:web:<minister-host>`, JWT `typ` == `vc+jwt`, a present and unexpired
+  `exp`, a well-formed `vc` envelope, and `credentialSubject.id` == the VC's
+  own `sub` (holder binding). A badge whose signature, issuer, type, expiry,
+  structure, or subject binding is wrong is rejected (dropped into `rejected`,
+  never thrown from `verifyBadges`).
+
+> **Issuer-domain coupling (all badges rejected?).** The expected badge issuer
+> is derived as `did:web:<host-of-your-configured-issuer>`. Minister signs badge
+> VCs with `did:web:<MINISTER_ISSUER_DOMAIN>`. If the Minister deployment's
+> `MINISTER_ISSUER_DOMAIN` host does not equal the OIDC issuer host, **every
+> badge fails verification** and lands in `rejected` with an issuer mismatch
+> (login and `id_token` verification are unaffected). If you see all badges
+> rejected, check that Minister's `MINISTER_ISSUER_DOMAIN` host matches its
+> OIDC issuer host.
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `createMinisterClient(config)` | Build a flow client bound to one Minister + RP. |
+| `client.getAuthorizationUrl(args)` | Discover the authorize endpoint and build the redirect URL. |
+| `client.exchangeCode(args)` | Token exchange + verify id_token + verify badges. Returns `{ claims, badges, rejected }`. |
+| `client.verifyMinisterBadge(vcJwt, opts?)` | Verify a single VC badge; `type` is a slug string (e.g. `"email-domain"`). |
+| `client.generatePkce()` | PKCE S256 `{ verifier, challenge }`. |
+| `client.randomToken(bytes?)` | URL-safe random `state` / `nonce`. |
+| `client.badgeScope(slug)` | `"badge:<slug>"` helper. |
+| `createMinisterVerifier(config)` | Configure-once verifier: `verifyIdToken`, `verifyBadges`, `verifyBadge`. |
+| `verifyMinisterIdToken`, `verifyMinisterBadges`, `verifyMinisterBadge` | The standalone verification functions. |
+| `badgeScope`, `badgeScopes`, `badgeTypeOf`, `knownBadgeTypes`, `getBadgeClaimSchema` | Badge vocabulary helpers. |
+| `MinisterTokenError` | Thrown when an `id_token` itself fails verification. |
+| `OidcFlowState`, `MinisterClaims`, `VerifiedBadge`, `BadgesResult`, `RejectedBadge`, ... | Public types. |
+| `VcVerificationError`, `OidcError`, `MinisterTokenError` | Error classes. |
+
+### Testing without the network
+
+`exchangeCode` and `verifyMinisterBadge` accept injectable key sources so your
+tests never hit Minister: pass `idTokenKey` / `badgeKey` (to `exchangeCode`) or
+`{ key }` (to `verifyMinisterBadge`) — a `KeyLike`, a `Uint8Array`, or a `jose`
+key-resolver function. The default is a remote JWKS fetched from Minister.
+
+## License
+
+MIT OR Apache-2.0

package/dist/auth-js.d.ts

@@ -0,0 +1,18 @@
+import { OIDCConfig } from '@auth/core/providers';
+import { JWTPayload } from 'jose';
+import { K as KeyInput, B as BadgesResult } from './types-BHY-mOJf.js';
+
+interface MinisterProviderOptions {
+    clientId: string;
+    clientSecret?: string;
+    issuer: string;
+    scopes?: string[];
+}
+declare function ministerProvider(options: MinisterProviderOptions): OIDCConfig<Record<string, unknown>>;
+interface MinisterBadgesFromProfileOptions {
+    issuer: string;
+    key?: KeyInput;
+}
+declare function ministerBadgesFromProfile(profile: JWTPayload | Record<string, unknown>, options: MinisterBadgesFromProfileOptions): Promise<BadgesResult>;
+
+export { type MinisterBadgesFromProfileOptions, type MinisterProviderOptions, ministerBadgesFromProfile, ministerProvider };

package/dist/auth-js.js

@@ -0,0 +1,27 @@
+import {
+  verifyMinisterBadges
+} from "./chunk-CSD6YO64.js";
+import "./chunk-U2JFQKFV.js";
+
+// src/auth-js.ts
+function ministerProvider(options) {
+  const scopes = options.scopes ?? ["openid", "profile"];
+  return {
+    id: "minister",
+    name: "Minister",
+    type: "oidc",
+    issuer: options.issuer,
+    clientId: options.clientId,
+    clientSecret: options.clientSecret,
+    authorization: { params: { scope: scopes.join(" ") } },
+    checks: ["pkce", "state", "nonce"]
+  };
+}
+function ministerBadgesFromProfile(profile, options) {
+  return verifyMinisterBadges(profile, { issuer: options.issuer, key: options.key });
+}
+export {
+  ministerBadgesFromProfile,
+  ministerProvider
+};
+//# sourceMappingURL=auth-js.js.map

package/dist/auth-js.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/auth-js.ts"],"sourcesContent":["// @minister/client/auth-js — non-invasive helpers for Auth.js (next-auth).\n// We do NOT modify Auth.js; these are values/functions you hand to it via\n// its documented extension points. `@auth/core` is a types-only optional\n// peer used solely for the OIDCConfig return type.\nimport type { OIDCConfig } from \"@auth/core/providers\";\nimport type { JWTPayload } from \"jose\";\nimport { verifyMinisterBadges } from \"./verify-badges\";\nimport type { KeyInput, BadgesResult } from \"./types\";\n\nexport interface MinisterProviderOptions {\n  clientId: string;\n  clientSecret?: string;\n  issuer: string;\n  // Defaults to [\"openid\", \"profile\"]. Add badge:<type> scopes to request badges.\n  scopes?: string[];\n}\n\n// Build the Auth.js OIDC provider config object. Drop it into\n// NextAuth({ providers: [ministerProvider({...})] }). Auth.js owns the\n// flow, session, and cookies; this is only its provider configuration.\nexport function ministerProvider(options: MinisterProviderOptions): OIDCConfig<Record<string, unknown>> {\n  const scopes = options.scopes ?? [\"openid\", \"profile\"];\n  return {\n    id: \"minister\",\n    name: \"Minister\",\n    type: \"oidc\",\n    issuer: options.issuer,\n    clientId: options.clientId,\n    clientSecret: options.clientSecret,\n    authorization: { params: { scope: scopes.join(\" \") } },\n    checks: [\"pkce\", \"state\", \"nonce\"],\n  };\n}\n\nexport interface MinisterBadgesFromProfileOptions {\n  issuer: string;\n  key?: KeyInput;\n}\n\n// Verify the minister_badges in an Auth.js `profile` (already-verified\n// id_token payload). Call inside your own jwt/profile callback.\nexport function ministerBadgesFromProfile(\n  profile: JWTPayload | Record<string, unknown>,\n  options: MinisterBadgesFromProfileOptions,\n): Promise<BadgesResult> {\n  return verifyMinisterBadges(profile as JWTPayload, { issuer: options.issuer, key: options.key });\n}\n"],"mappings":";;;;;;AAoBO,SAAS,iBAAiB,SAAuE;AACtG,QAAM,SAAS,QAAQ,UAAU,CAAC,UAAU,SAAS;AACrD,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,MAAM;AAAA,IACN,MAAM;AAAA,IACN,QAAQ,QAAQ;AAAA,IAChB,UAAU,QAAQ;AAAA,IAClB,cAAc,QAAQ;AAAA,IACtB,eAAe,EAAE,QAAQ,EAAE,OAAO,OAAO,KAAK,GAAG,EAAE,EAAE;AAAA,IACrD,QAAQ,CAAC,QAAQ,SAAS,OAAO;AAAA,EACnC;AACF;AASO,SAAS,0BACd,SACA,SACuB;AACvB,SAAO,qBAAqB,SAAuB,EAAE,QAAQ,QAAQ,QAAQ,KAAK,QAAQ,IAAI,CAAC;AACjG;","names":[]}

package/dist/badges/index.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+
+declare const EmailDomainClaims: z.ZodObject<{
+    domain: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    domain: string;
+}, {
+    domain: string;
+}>;
+type EmailDomainClaims = z.infer<typeof EmailDomainClaims>;
+declare const EmailExactClaims: z.ZodObject<{
+    email: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    email: string;
+}, {
+    email: string;
+}>;
+type EmailExactClaims = z.infer<typeof EmailExactClaims>;
+declare const OAUTH_PROVIDERS: readonly ["github", "google", "discord"];
+declare const OAuthAccountClaims: z.ZodObject<{
+    provider: z.ZodEnum<["github", "google", "discord"]>;
+    accountId: z.ZodString;
+    handle: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    provider: "github" | "google" | "discord";
+    accountId: string;
+    handle?: string | undefined;
+}, {
+    provider: "github" | "google" | "discord";
+    accountId: string;
+    handle?: string | undefined;
+}>;
+type OAuthAccountClaims = z.infer<typeof OAuthAccountClaims>;
+declare const AGE_THRESHOLDS: readonly [16, 18, 21, 25, 30, 35, 40, 45, 55, 65];
+type AgeThreshold = (typeof AGE_THRESHOLDS)[number];
+declare const AgeOverClaimsFor: (threshold: AgeThreshold) => z.ZodObject<{
+    threshold: z.ZodLiteral<16 | 18 | 21 | 25 | 30 | 35 | 40 | 45 | 55 | 65>;
+}, "strip", z.ZodTypeAny, {
+    threshold: 16 | 18 | 21 | 25 | 30 | 35 | 40 | 45 | 55 | 65;
+}, {
+    threshold: 16 | 18 | 21 | 25 | 30 | 35 | 40 | 45 | 55 | 65;
+}>;
+declare const ResidencyCountryClaims: z.ZodObject<{
+    country: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    country: string;
+}, {
+    country: string;
+}>;
+type ResidencyCountryClaims = z.infer<typeof ResidencyCountryClaims>;
+declare const ResidencyStateClaims: z.ZodObject<{
+    country: z.ZodString;
+    state: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    state: string;
+    country: string;
+}, {
+    state: string;
+    country: string;
+}>;
+type ResidencyStateClaims = z.infer<typeof ResidencyStateClaims>;
+declare const ResidencyCityClaims: z.ZodObject<{
+    country: z.ZodString;
+    state: z.ZodString;
+    city: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    state: string;
+    country: string;
+    city: string;
+}, {
+    state: string;
+    country: string;
+    city: string;
+}>;
+type ResidencyCityClaims = z.infer<typeof ResidencyCityClaims>;
+declare const InviteCodeClaims: z.ZodObject<{
+    label: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+}, {
+    label: string;
+}>;
+type InviteCodeClaims = z.infer<typeof InviteCodeClaims>;
+declare const TlsnAttestationClaims: z.ZodObject<{
+    domain: z.ZodString;
+    claim: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    domain: string;
+    claim: string;
+}, {
+    domain: string;
+    claim: string;
+}>;
+type TlsnAttestationClaims = z.infer<typeof TlsnAttestationClaims>;
+
+interface BadgeTypeDef {
+    slug: string;
+    credentialType: string;
+    scope: string;
+    claims: z.ZodType<unknown>;
+}
+declare function defineBadgeType(input: {
+    slug: string;
+    credentialType: string;
+    claims: z.ZodType<unknown>;
+}): BadgeTypeDef;
+declare const BADGE_TYPES: Record<string, BadgeTypeDef>;
+declare function slugForCredentialType(credentialType: string): string | undefined;
+
+declare function badgeScope(slug: string): string;
+declare function badgeScopes(slugs: string[]): string[];
+declare function badgeTypeOf(vcType: string[]): string | undefined;
+declare function getBadgeClaimSchema(slug: string): z.ZodType<unknown> | undefined;
+declare function knownBadgeTypes(): string[];
+
+export { AGE_THRESHOLDS, AgeOverClaimsFor, type AgeThreshold, BADGE_TYPES, type BadgeTypeDef, EmailDomainClaims, EmailExactClaims, InviteCodeClaims, OAUTH_PROVIDERS, OAuthAccountClaims, ResidencyCityClaims, ResidencyCountryClaims, ResidencyStateClaims, TlsnAttestationClaims, badgeScope, badgeScopes, badgeTypeOf, defineBadgeType, getBadgeClaimSchema, knownBadgeTypes, slugForCredentialType };

package/dist/badges/index.js

@@ -0,0 +1,44 @@
+import "../chunk-R4XGCZVA.js";
+import {
+  AGE_THRESHOLDS,
+  AgeOverClaimsFor,
+  BADGE_TYPES,
+  EmailDomainClaims,
+  EmailExactClaims,
+  InviteCodeClaims,
+  OAUTH_PROVIDERS,
+  OAuthAccountClaims,
+  ResidencyCityClaims,
+  ResidencyCountryClaims,
+  ResidencyStateClaims,
+  TlsnAttestationClaims,
+  badgeScope,
+  badgeScopes,
+  badgeTypeOf,
+  defineBadgeType,
+  getBadgeClaimSchema,
+  knownBadgeTypes,
+  slugForCredentialType
+} from "../chunk-U2JFQKFV.js";
+export {
+  AGE_THRESHOLDS,
+  AgeOverClaimsFor,
+  BADGE_TYPES,
+  EmailDomainClaims,
+  EmailExactClaims,
+  InviteCodeClaims,
+  OAUTH_PROVIDERS,
+  OAuthAccountClaims,
+  ResidencyCityClaims,
+  ResidencyCountryClaims,
+  ResidencyStateClaims,
+  TlsnAttestationClaims,
+  badgeScope,
+  badgeScopes,
+  badgeTypeOf,
+  defineBadgeType,
+  getBadgeClaimSchema,
+  knownBadgeTypes,
+  slugForCredentialType
+};
+//# sourceMappingURL=index.js.map

package/dist/badges/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}