@payez/next-mvp 4.8.3 → 4.8.5

package/README.md

@@ -499,6 +499,33 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
 ---
 
+## Register an agent (REG-002)
+
+`@payez/next-mvp/agents` is a typed client over the tenant-admin agent door (`POST/GET api/client/agents`). The caller must be a tenant admin with completed MFA; the client (tenant) comes from the token, so there is no client id to pass.
+
+```ts
+import { createAgentRegistryClient, AgentRegistryError } from '@payez/next-mvp/agents';
+
+const agents = createAgentRegistryClient({
+  baseUrl: process.env.IDP_URL!,            // absolute origin of the identity service
+  accessToken: () => getAdminAccessToken(), // a string, or a function returning one
+});
+
+try {
+  const { item } = await agents.register({ user_name: 'build-bot', owner_user_id: 42, host_class: 'rig_pane' });
+  // item.status.code === 'PENDING': the first mint is refused AGENT_PENDING until an admin activates it.
+} catch (e) {
+  if (e instanceof AgentRegistryError) {
+    // e.code is Core's code as-is: VALIDATION_ERROR, OWNER_NOT_ELIGIBLE, OWNER_NOT_MEMBER, AGENT_NAME_TAKEN, ...
+    // e.status is the HTTP status (0 = no response). Nothing is retried; a 409 AGENT_NAME_TAKEN stays a 409.
+  }
+  throw e;
+}
+
+const { items } = await agents.list();  // every agent of your client
+const { item: one } = await agents.get(41);
+```
+
 ## API Routes
 
 Access pre-built API handlers:

package/dist/agents/index.d.ts

@@ -0,0 +1 @@
+export * from './registry';

package/dist/agents/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./registry"), exports);

package/dist/agents/registry.d.ts

@@ -0,0 +1,73 @@
+/** Core PayEzEndpoints.AgentTokens.AllowedHostClasses (PayEzEndpoints.cs:187,194,228). The server is the authority; this is for typing only. */
+export declare const AGENT_HOST_CLASSES: readonly ["rig_pane", "contractor"];
+export type AgentHostClass = (typeof AGENT_HOST_CLASSES)[number];
+export interface RegisterAgentInput {
+    /** 3-64 chars, letters/digits/'.'/'_'/'-', starting with a letter or digit; unique across the IdP. */
+    user_name: string;
+    /** A person (user id) who is an approved, active member of this client. */
+    owner_user_id: number;
+    host_class: AgentHostClass;
+}
+export interface AgentRecord {
+    id: number;
+    user_name: string;
+    owner: {
+        kind: 'person';
+        user_id: number;
+        display_name: string | null;
+        approved: boolean;
+    } | null;
+    status: {
+        code: string;
+        reason: string | null;
+    };
+    host_class: string | null;
+    agent_profile_id: number | null;
+}
+export interface MintableApp {
+    id: number;
+    name: string;
+    allowed_scopes: unknown;
+}
+export interface RegisterAgentResult {
+    item: AgentRecord | null;
+    created: boolean;
+    audited: boolean;
+}
+export interface ListAgentsResult {
+    client_id: number;
+    demo_token_ready: boolean | null;
+    items: AgentRecord[];
+    apps: MintableApp[];
+}
+export interface GetAgentResult {
+    item: AgentRecord;
+    apps: MintableApp[];
+}
+/** Codes this door is known to answer. `string` stays in the union: an unknown code is surfaced, not hidden. */
+export type AgentRegistryErrorCode = 'VALIDATION_ERROR' | 'OWNER_NOT_ELIGIBLE' | 'OWNER_NOT_MEMBER' | 'AGENT_NAME_TAKEN' | 'AUDIT_WRITE_FAILED_NOT_APPLIED' | 'MISSING_CLIENT_ID' | 'UNAUTHORIZED' | 'IDP_UNREACHABLE' | 'NETWORK_ERROR' | 'BAD_RESPONSE' | (string & {});
+export declare class AgentRegistryError extends Error {
+    readonly code: AgentRegistryErrorCode;
+    /** HTTP status; 0 when no response arrived. */
+    readonly status: number;
+    readonly requestId?: string;
+    readonly details?: unknown;
+    constructor(code: AgentRegistryErrorCode, message: string, status: number, extra?: {
+        requestId?: string;
+        details?: unknown;
+    });
+}
+export interface AgentRegistryClientOptions {
+    /** Absolute origin of the identity service (e.g. IDP_URL). */
+    baseUrl: string;
+    /** A tenant-admin access token (completed MFA), or a function that returns one. */
+    accessToken: string | (() => string | Promise<string>);
+    /** Override for tests; defaults to bearerFetch (global fetch, never follows a redirect). */
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+}
+export interface AgentRegistryClient {
+    register(input: RegisterAgentInput): Promise<RegisterAgentResult>;
+    list(): Promise<ListAgentsResult>;
+    get(id: number): Promise<GetAgentResult>;
+}
+export declare function createAgentRegistryClient(options: AgentRegistryClientOptions): AgentRegistryClient;

package/dist/agents/registry.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRegistryError = exports.AGENT_HOST_CLASSES = void 0;
+exports.createAgentRegistryClient = createAgentRegistryClient;
+/**
+ * REG-002 (Keel Registry): the SDK half of "Registration API and SDK".
+ *
+ * A typed client over the tenant-admin agent door in PayEz-Core:
+ *   PayEz.Apis/PayEz.External.Id.Api/Controllers/ClientAgentsController.cs @ 22d44a34c
+ *     POST api/client/agents       Register  (:332-367)  body { user_name, owner_user_id, host_class } -> 201 { item, created, audited }
+ *     GET  api/client/agents       List      (:92-107)   -> { client_id, demo_token_ready, items, apps }
+ *     GET  api/client/agents/{id}  Get       (:126-133)  -> { item, apps } | 404
+ *   Gate: payez_admin / idp_admin_ui_graft_admin with completed MFA (:39-40). The client comes from the TOKEN, never from the
+ *   body, so this client has no client-id argument and cannot register into another client.
+ *
+ * Contract this client keeps:
+ *   - a refusal is thrown as an AgentRegistryError carrying the server's `code` AS-IS (VALIDATION_ERROR, OWNER_NOT_ELIGIBLE,
+ *     OWNER_NOT_MEMBER, AGENT_NAME_TAKEN, AUDIT_WRITE_FAILED_NOT_APPLIED, MISSING_CLIENT_ID, UNAUTHORIZED, ...). It is never
+ *     re-worded, mapped, or swallowed.
+ *   - NO RETRY, of any status. A 409 AGENT_NAME_TAKEN means the name exists; sending it again can only repeat the answer, and a
+ *     register that timed out may have been applied, so the caller (who can read the list) decides, not this client.
+ *   - no validation of the body before sending: the server's validation is the authority and its code is what the caller gets.
+ *   - the bearer never follows a redirect (bearerFetch) and is never put in an error, a message or a log line.
+ *
+ * A newly registered agent is PENDING until an admin activates it (PAY-2069); its first mint is refused AGENT_PENDING.
+ */
+const bearer_fetch_1 = require("../lib/bearer-fetch");
+const idp_url_guard_1 = require("../lib/idp-url-guard");
+/** Core PayEzEndpoints.AgentTokens.AllowedHostClasses (PayEzEndpoints.cs:187,194,228). The server is the authority; this is for typing only. */
+exports.AGENT_HOST_CLASSES = ['rig_pane', 'contractor'];
+class AgentRegistryError extends Error {
+    code;
+    /** HTTP status; 0 when no response arrived. */
+    status;
+    requestId;
+    details;
+    constructor(code, message, status, extra) {
+        super(message);
+        this.name = 'AgentRegistryError';
+        this.code = code;
+        this.status = status;
+        this.requestId = extra?.requestId;
+        this.details = extra?.details;
+    }
+}
+exports.AgentRegistryError = AgentRegistryError;
+function createAgentRegistryClient(options) {
+    (0, idp_url_guard_1.assertAbsoluteIdpUrl)(options.baseUrl);
+    const base = options.baseUrl.replace(/\/+$/, '');
+    const send = options.fetch ?? ((input, init) => (0, bearer_fetch_1.bearerFetch)(input, init));
+    async function call(path, init) {
+        const token = typeof options.accessToken === 'function' ? await options.accessToken() : options.accessToken;
+        let res;
+        try {
+            res = await send(`${base}${path}`, {
+                method: init.method,
+                headers: {
+                    Accept: 'application/json',
+                    ...(init.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+                    Authorization: `Bearer ${token}`,
+                },
+                ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+                cache: 'no-store',
+            });
+        }
+        catch {
+            // Fixed text: a transport error's own message can carry the URL or headers.
+            // A POST that failed in transit may still have been applied (the server can answer after the client gave up), so for register the text says the
+            // outcome is unknown and to read the list; it is never retried here. A GET changes nothing, so it keeps the plain text.
+            throw new AgentRegistryError('NETWORK_ERROR', init.method === 'POST'
+                ? 'The identity service could not be reached; the outcome is unknown, so read the list before registering again'
+                : 'The identity service could not be reached', 0);
+        }
+        let json = null;
+        try {
+            json = await res.json();
+        }
+        catch {
+            json = null;
+        }
+        if (!res.ok) {
+            const e = json?.error;
+            throw new AgentRegistryError(typeof e?.code === 'string' ? e.code : `HTTP_${res.status}`, typeof e?.message === 'string' ? e.message : `The identity service answered ${res.status}`, res.status, { requestId: json?.request_id ?? e?.support?.request_id, details: e?.details });
+        }
+        const data = json?.data;
+        if (json?.success === false || data == null || typeof data !== 'object') {
+            throw new AgentRegistryError('BAD_RESPONSE', 'The identity service answered without the expected data', res.status);
+        }
+        return data;
+    }
+    return {
+        register: (input) => call('/api/client/agents', {
+            method: 'POST',
+            // Exactly the three fields the door binds; nothing else is forwarded.
+            body: { user_name: input.user_name, owner_user_id: input.owner_user_id, host_class: input.host_class },
+        }),
+        list: () => call('/api/client/agents', { method: 'GET' }),
+        get: (id) => call(`/api/client/agents/${encodeURIComponent(String(id))}`, { method: 'GET' }),
+    };
+}

package/dist/components/auth/CredentialSignInForm.js

@@ -9,6 +9,7 @@ const TraditionalAuthSection_1 = require("./TraditionalAuthSection");
 const safe_callback_1 = require("../../auth/safe-callback");
 const authorize_resume_1 = require("../../lib/authorize-resume");
 const code_step_copy_1 = require("../../lib/code-step-copy");
+const DevCodeNotice_1 = require("./DevCodeNotice");
 const credential_sign_in_client_1 = require("../../lib/credential-sign-in-client");
 const inputStyle = {
     borderColor: 'var(--border-default, #e5e7eb)',
@@ -39,6 +40,7 @@ function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPa
     const [fieldError, setFieldError] = (0, react_1.useState)(null);
     const [codeRequest, setCodeRequest] = (0, react_1.useState)(code_step_copy_1.NO_CODE_REQUEST);
     const [offerEmailCode, setOfferEmailCode] = (0, react_1.useState)(false);
+    const [devCode, setDevCode] = (0, react_1.useState)(null);
     const [emailCodeMsg, setEmailCodeMsg] = (0, react_1.useState)(null);
     async function submit(withCode) {
         setBusy(true);
@@ -56,6 +58,7 @@ function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPa
             }
             if (r.kind === 'two_factor') {
                 setCodeRequest(r.codeRequest);
+                setDevCode(r.devCode);
                 setStep('code');
                 return;
             }
@@ -90,6 +93,7 @@ function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPa
     function onBack() {
         setStep('credentials');
         setCodeRequest(code_step_copy_1.NO_CODE_REQUEST);
+        setDevCode(null);
         setCode('');
         setFieldError(null);
         setError(null);
@@ -103,6 +107,7 @@ function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPa
             const r = await (0, credential_sign_in_client_1.requestEmailCode)(fetchImpl);
             if (r.kind === 'requested') {
                 setCodeRequest(r.codeRequest);
+                setDevCode(r.devCode);
                 setError(null);
                 setOfferEmailCode(false);
                 setEmailCodeMsg('We asked for a code to be emailed to you. Enter it above when it arrives.');
@@ -121,7 +126,7 @@ function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showForgotPa
         return ((0, jsx_runtime_1.jsxs)("div", { "data-testid": "credential-sign-in-code-step", className: "text-left", children: [(0, jsx_runtime_1.jsx)("p", { className: "text-sm mb-4", style: { color: 'var(--text-primary, #111827)' }, children: (0, code_step_copy_1.codeStepInstruction)(email, codeRequest) }), (0, jsx_runtime_1.jsxs)("form", { onSubmit: onCodeSubmit, noValidate: true, className: "space-y-4", children: [(0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("label", { htmlFor: "credential-code", className: "block text-sm font-medium mb-2", style: { color: 'var(--text-primary, #111827)' }, children: "Authentication code" }), (0, jsx_runtime_1.jsx)("input", { id: "credential-code", name: "code", type: "text", inputMode: "numeric", autoComplete: "one-time-code", required: true, placeholder: "000000", value: code, disabled: busy, onChange: (e) => {
                                         setCode(e.target.value);
                                         setFieldError(null);
-                                    }, className: "w-full px-4 py-3 rounded-lg border transition-colors focus:outline-none focus:ring-2 disabled:opacity-50", style: inputStyle })] }), (0, jsx_runtime_1.jsx)("button", { type: "submit", disabled: busy, className: "w-full py-3 px-4 rounded-lg font-semibold focus:outline-none focus:ring-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors", style: { background: 'var(--btn-primary-bg, #11B588)', color: 'var(--btn-primary-text, white)' }, children: busy ? 'Verifying…' : 'Verify' })] }), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: onBack, disabled: busy, className: "text-sm underline mt-4", style: { background: 'none', border: 'none', padding: 0, color: 'var(--text-muted, #6b7280)' }, children: "Back" }), problemLine, (offerEmailCode || emailCodeMsg) && ((0, jsx_runtime_1.jsxs)("div", { "data-testid": "email-code-offer", className: "mt-4", children: [offerEmailCode && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: () => void askForEmailCode(), disabled: busy, className: "text-sm font-semibold underline", style: { background: 'none', border: 'none', padding: 0, color: 'var(--text-primary, #111827)' }, children: "Email me a code instead" })), emailCodeMsg && ((0, jsx_runtime_1.jsx)("p", { role: "status", "data-testid": "email-code-offer-msg", className: "text-sm mt-2", style: { color: 'var(--text-primary, #111827)' }, children: emailCodeMsg }))] }))] }));
+                                    }, className: "w-full px-4 py-3 rounded-lg border transition-colors focus:outline-none focus:ring-2 disabled:opacity-50", style: inputStyle }), (0, jsx_runtime_1.jsx)(DevCodeNotice_1.DevCodeNotice, { code: devCode })] }), (0, jsx_runtime_1.jsx)("button", { type: "submit", disabled: busy, className: "w-full py-3 px-4 rounded-lg font-semibold focus:outline-none focus:ring-2 disabled:opacity-50 disabled:cursor-not-allowed transition-colors", style: { background: 'var(--btn-primary-bg, #11B588)', color: 'var(--btn-primary-text, white)' }, children: busy ? 'Verifying…' : 'Verify' })] }), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: onBack, disabled: busy, className: "text-sm underline mt-4", style: { background: 'none', border: 'none', padding: 0, color: 'var(--text-muted, #6b7280)' }, children: "Back" }), problemLine, (offerEmailCode || emailCodeMsg) && ((0, jsx_runtime_1.jsxs)("div", { "data-testid": "email-code-offer", className: "mt-4", children: [offerEmailCode && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: () => void askForEmailCode(), disabled: busy, className: "text-sm font-semibold underline", style: { background: 'none', border: 'none', padding: 0, color: 'var(--text-primary, #111827)' }, children: "Email me a code instead" })), emailCodeMsg && ((0, jsx_runtime_1.jsx)("p", { role: "status", "data-testid": "email-code-offer-msg", className: "text-sm mt-2", style: { color: 'var(--text-primary, #111827)' }, children: emailCodeMsg }))] }))] }));
     }
     return ((0, jsx_runtime_1.jsxs)("div", { "data-testid": "credential-sign-in", className: "text-left", children: [(0, jsx_runtime_1.jsx)(TraditionalAuthSection_1.TraditionalAuthSection, { email: email, password: password, onEmailChange: (v) => {
                     setEmail(v);

package/dist/components/auth/DevCodeNotice.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTH-045 (BAPert 75627): on a DEV identity service that echoes the emailed sign-in code in its own answer (Email:DevCodeEcho, an
+ * IdP setting that is on only in Development), the sign-in form shows that code under the code box, because on a dev rig the email
+ * goes to nobody. This component is a PURE PASSTHROUGH of the server's `devVerificationCode`: it renders nothing unless it is given
+ * a non-empty string, and CredentialSignInForm gives it nothing but the value the door returned. There is no environment flag in the
+ * app, so a production IdP (echo off, field absent) can never make it appear.
+ */
+export declare function DevCodeNotice({ code }: {
+    code?: string | null;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/auth/DevCodeNotice.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DevCodeNotice = DevCodeNotice;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * AUTH-045 (BAPert 75627): on a DEV identity service that echoes the emailed sign-in code in its own answer (Email:DevCodeEcho, an
+ * IdP setting that is on only in Development), the sign-in form shows that code under the code box, because on a dev rig the email
+ * goes to nobody. This component is a PURE PASSTHROUGH of the server's `devVerificationCode`: it renders nothing unless it is given
+ * a non-empty string, and CredentialSignInForm gives it nothing but the value the door returned. There is no environment flag in the
+ * app, so a production IdP (echo off, field absent) can never make it appear.
+ */
+function DevCodeNotice({ code }) {
+    if (typeof code !== 'string' || code === '')
+        return null;
+    return ((0, jsx_runtime_1.jsxs)("p", { "data-testid": "dev-sign-in-code", className: "text-sm mt-3", style: { color: 'var(--text-muted, #6b7280)' }, children: ["Development sign-in code: ", (0, jsx_runtime_1.jsx)("strong", { children: code })] }));
+}

package/dist/lib/credential-sign-in-client.d.ts

@@ -22,6 +22,7 @@ export type CredentialSignInResult = {
 } | {
     kind: 'two_factor';
     codeRequest: CodeRequest;
+    devCode: string | null;
 } | {
     kind: 'rate_limited';
     message: string;

package/dist/lib/credential-sign-in-client.js

@@ -43,6 +43,10 @@ function validateCredentials(email, password) {
         errors.password = 'Enter your password.';
     return errors.email || errors.password ? errors : null;
 }
+/** The dev echo: the door passes the IdP's DevVerificationCode through as `devVerificationCode`. Nothing else is ever a dev code. */
+function readDevCode(body) {
+    return typeof body?.devVerificationCode === 'string' && body.devVerificationCode ? body.devVerificationCode : null;
+}
 function asString(v) {
     return typeof v === 'string' && v ? v : undefined;
 }
@@ -58,7 +62,7 @@ async function credentialSignIn(args, fetchImpl = (input, init) => fetch(input,
         if (res.status === 429)
             return { kind: 'rate_limited', message: asString(body?.error) ?? exports.MSG_RATE_LIMITED };
         if (body?.requiresTwoFactor)
-            return { kind: 'two_factor', codeRequest: (0, code_step_copy_1.readCodeRequest)(body) };
+            return { kind: 'two_factor', codeRequest: (0, code_step_copy_1.readCodeRequest)(body), devCode: readDevCode(body) };
         if (!res.ok || body?.success !== true) {
             return { kind: 'error', message: asString(body?.error) ?? exports.MSG_CANNOT_SIGN_IN, offerEmailCode: body?.offerEmailCode === true };
         }
@@ -78,7 +82,7 @@ async function requestEmailCode(fetchImpl = (input, init) => fetch(input, init))
             return {
                 kind: 'requested',
                 codeRequest: (0, code_step_copy_1.readCodeRequest)(body),
-                devCode: typeof body?.devVerificationCode === 'string' && body.devVerificationCode ? body.devVerificationCode : null,
+                devCode: readDevCode(body),
             };
         }
         return { kind: 'error', message: asString(body?.error) ?? exports.MSG_EMAIL_CODE_FAILED };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payez/next-mvp",
-  "version": "4.8.3",
+  "version": "4.8.5",
   "sideEffects": false,
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -810,6 +810,11 @@
       "require": "./dist/hooks/useViabilitySession.js",
       "default": "./dist/hooks/useViabilitySession.js"
     },
+    "./agents": {
+      "types": "./dist/agents/index.d.ts",
+      "require": "./dist/agents/index.js",
+      "default": "./dist/agents/index.js"
+    },
     "./vibe": {
       "types": "./dist/vibe/index.d.ts",
       "require": "./dist/vibe/index.js",

package/src/agents/index.ts

@@ -0,0 +1 @@
+export * from './registry';

package/src/agents/registry.ts

@@ -0,0 +1,179 @@
+/**
+ * REG-002 (Keel Registry): the SDK half of "Registration API and SDK".
+ *
+ * A typed client over the tenant-admin agent door in PayEz-Core:
+ *   PayEz.Apis/PayEz.External.Id.Api/Controllers/ClientAgentsController.cs @ 22d44a34c
+ *     POST api/client/agents       Register  (:332-367)  body { user_name, owner_user_id, host_class } -> 201 { item, created, audited }
+ *     GET  api/client/agents       List      (:92-107)   -> { client_id, demo_token_ready, items, apps }
+ *     GET  api/client/agents/{id}  Get       (:126-133)  -> { item, apps } | 404
+ *   Gate: payez_admin / idp_admin_ui_graft_admin with completed MFA (:39-40). The client comes from the TOKEN, never from the
+ *   body, so this client has no client-id argument and cannot register into another client.
+ *
+ * Contract this client keeps:
+ *   - a refusal is thrown as an AgentRegistryError carrying the server's `code` AS-IS (VALIDATION_ERROR, OWNER_NOT_ELIGIBLE,
+ *     OWNER_NOT_MEMBER, AGENT_NAME_TAKEN, AUDIT_WRITE_FAILED_NOT_APPLIED, MISSING_CLIENT_ID, UNAUTHORIZED, ...). It is never
+ *     re-worded, mapped, or swallowed.
+ *   - NO RETRY, of any status. A 409 AGENT_NAME_TAKEN means the name exists; sending it again can only repeat the answer, and a
+ *     register that timed out may have been applied, so the caller (who can read the list) decides, not this client.
+ *   - no validation of the body before sending: the server's validation is the authority and its code is what the caller gets.
+ *   - the bearer never follows a redirect (bearerFetch) and is never put in an error, a message or a log line.
+ *
+ * A newly registered agent is PENDING until an admin activates it (PAY-2069); its first mint is refused AGENT_PENDING.
+ */
+import { bearerFetch } from '../lib/bearer-fetch';
+import { assertAbsoluteIdpUrl } from '../lib/idp-url-guard';
+
+/** Core PayEzEndpoints.AgentTokens.AllowedHostClasses (PayEzEndpoints.cs:187,194,228). The server is the authority; this is for typing only. */
+export const AGENT_HOST_CLASSES = ['rig_pane', 'contractor'] as const;
+export type AgentHostClass = (typeof AGENT_HOST_CLASSES)[number];
+
+export interface RegisterAgentInput {
+  /** 3-64 chars, letters/digits/'.'/'_'/'-', starting with a letter or digit; unique across the IdP. */
+  user_name: string;
+  /** A person (user id) who is an approved, active member of this client. */
+  owner_user_id: number;
+  host_class: AgentHostClass;
+}
+
+export interface AgentRecord {
+  id: number;
+  user_name: string;
+  owner: { kind: 'person'; user_id: number; display_name: string | null; approved: boolean } | null;
+  status: { code: string; reason: string | null };
+  host_class: string | null;
+  agent_profile_id: number | null;
+}
+
+export interface MintableApp {
+  id: number;
+  name: string;
+  allowed_scopes: unknown;
+}
+
+export interface RegisterAgentResult {
+  item: AgentRecord | null;
+  created: boolean;
+  audited: boolean;
+}
+
+export interface ListAgentsResult {
+  client_id: number;
+  demo_token_ready: boolean | null;
+  items: AgentRecord[];
+  apps: MintableApp[];
+}
+
+export interface GetAgentResult {
+  item: AgentRecord;
+  apps: MintableApp[];
+}
+
+/** Codes this door is known to answer. `string` stays in the union: an unknown code is surfaced, not hidden. */
+export type AgentRegistryErrorCode =
+  | 'VALIDATION_ERROR'
+  | 'OWNER_NOT_ELIGIBLE'
+  | 'OWNER_NOT_MEMBER'
+  | 'AGENT_NAME_TAKEN'
+  | 'AUDIT_WRITE_FAILED_NOT_APPLIED'
+  | 'MISSING_CLIENT_ID'
+  | 'UNAUTHORIZED'
+  | 'IDP_UNREACHABLE'
+  | 'NETWORK_ERROR'
+  | 'BAD_RESPONSE'
+  | (string & {});
+
+export class AgentRegistryError extends Error {
+  readonly code: AgentRegistryErrorCode;
+  /** HTTP status; 0 when no response arrived. */
+  readonly status: number;
+  readonly requestId?: string;
+  readonly details?: unknown;
+
+  constructor(code: AgentRegistryErrorCode, message: string, status: number, extra?: { requestId?: string; details?: unknown }) {
+    super(message);
+    this.name = 'AgentRegistryError';
+    this.code = code;
+    this.status = status;
+    this.requestId = extra?.requestId;
+    this.details = extra?.details;
+  }
+}
+
+export interface AgentRegistryClientOptions {
+  /** Absolute origin of the identity service (e.g. IDP_URL). */
+  baseUrl: string;
+  /** A tenant-admin access token (completed MFA), or a function that returns one. */
+  accessToken: string | (() => string | Promise<string>);
+  /** Override for tests; defaults to bearerFetch (global fetch, never follows a redirect). */
+  fetch?: (input: string, init: RequestInit) => Promise<Response>;
+}
+
+export interface AgentRegistryClient {
+  register(input: RegisterAgentInput): Promise<RegisterAgentResult>;
+  list(): Promise<ListAgentsResult>;
+  get(id: number): Promise<GetAgentResult>;
+}
+
+export function createAgentRegistryClient(options: AgentRegistryClientOptions): AgentRegistryClient {
+  assertAbsoluteIdpUrl(options.baseUrl);
+  const base = options.baseUrl.replace(/\/+$/, '');
+  const send = options.fetch ?? ((input: string, init: RequestInit) => bearerFetch(input, init));
+
+  async function call<T>(path: string, init: { method: 'GET' | 'POST'; body?: unknown }): Promise<T> {
+    const token = typeof options.accessToken === 'function' ? await options.accessToken() : options.accessToken;
+    let res: Response;
+    try {
+      res = await send(`${base}${path}`, {
+        method: init.method,
+        headers: {
+          Accept: 'application/json',
+          ...(init.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+          Authorization: `Bearer ${token}`,
+        },
+        ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+        cache: 'no-store',
+      });
+    } catch {
+      // Fixed text: a transport error's own message can carry the URL or headers.
+      // A POST that failed in transit may still have been applied (the server can answer after the client gave up), so for register the text says the
+      // outcome is unknown and to read the list; it is never retried here. A GET changes nothing, so it keeps the plain text.
+      throw new AgentRegistryError(
+        'NETWORK_ERROR',
+        init.method === 'POST'
+          ? 'The identity service could not be reached; the outcome is unknown, so read the list before registering again'
+          : 'The identity service could not be reached',
+        0,
+      );
+    }
+
+    let json: any = null;
+    try { json = await res.json(); } catch { json = null; }
+
+    if (!res.ok) {
+      const e = json?.error;
+      throw new AgentRegistryError(
+        typeof e?.code === 'string' ? e.code : `HTTP_${res.status}`,
+        typeof e?.message === 'string' ? e.message : `The identity service answered ${res.status}`,
+        res.status,
+        { requestId: json?.request_id ?? e?.support?.request_id, details: e?.details },
+      );
+    }
+
+    const data = json?.data;
+    if (json?.success === false || data == null || typeof data !== 'object') {
+      throw new AgentRegistryError('BAD_RESPONSE', 'The identity service answered without the expected data', res.status);
+    }
+    return data as T;
+  }
+
+  return {
+    register: (input) =>
+      call<RegisterAgentResult>('/api/client/agents', {
+        method: 'POST',
+        // Exactly the three fields the door binds; nothing else is forwarded.
+        body: { user_name: input.user_name, owner_user_id: input.owner_user_id, host_class: input.host_class },
+      }),
+    list: () => call<ListAgentsResult>('/api/client/agents', { method: 'GET' }),
+    get: (id) => call<GetAgentResult>(`/api/client/agents/${encodeURIComponent(String(id))}`, { method: 'GET' }),
+  };
+}

package/src/components/auth/CredentialSignInForm.tsx

@@ -5,6 +5,7 @@ import { TraditionalAuthSection } from './TraditionalAuthSection';
 import { safeCallbackPath } from '../../auth/safe-callback';
 import { authorizeResumeHref } from '../../lib/authorize-resume';
 import { NO_CODE_REQUEST, codeStepInstruction, type CodeRequest } from '../../lib/code-step-copy';
+import { DevCodeNotice } from './DevCodeNotice';
 import {
   credentialSignIn,
   requestEmailCode,
@@ -73,6 +74,7 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
   const [fieldError, setFieldError] = useState<string | null>(null);
   const [codeRequest, setCodeRequest] = useState<CodeRequest>(NO_CODE_REQUEST);
   const [offerEmailCode, setOfferEmailCode] = useState(false);
+  const [devCode, setDevCode] = useState<string | null>(null);
   const [emailCodeMsg, setEmailCodeMsg] = useState<string | null>(null);
 
   async function submit(withCode?: string) {
@@ -89,6 +91,7 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
       }
       if (r.kind === 'two_factor') {
         setCodeRequest(r.codeRequest);
+        setDevCode(r.devCode);
         setStep('code');
         return;
       }
@@ -124,6 +127,7 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
   function onBack() {
     setStep('credentials');
     setCodeRequest(NO_CODE_REQUEST);
+    setDevCode(null);
     setCode('');
     setFieldError(null);
     setError(null);
@@ -138,6 +142,7 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
       const r = await requestEmailCode(fetchImpl);
       if (r.kind === 'requested') {
         setCodeRequest(r.codeRequest);
+        setDevCode(r.devCode);
         setError(null);
         setOfferEmailCode(false);
         setEmailCodeMsg('We asked for a code to be emailed to you. Enter it above when it arrives.');
@@ -182,6 +187,7 @@ export function CredentialSignInForm({ callbackUrl, fetchImpl, onSignedIn, showF
               className="w-full px-4 py-3 rounded-lg border transition-colors focus:outline-none focus:ring-2 disabled:opacity-50"
               style={inputStyle}
             />
+            <DevCodeNotice code={devCode} />
           </div>
           <button
             type="submit"

package/src/components/auth/DevCodeNotice.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+
+/**
+ * AUTH-045 (BAPert 75627): on a DEV identity service that echoes the emailed sign-in code in its own answer (Email:DevCodeEcho, an
+ * IdP setting that is on only in Development), the sign-in form shows that code under the code box, because on a dev rig the email
+ * goes to nobody. This component is a PURE PASSTHROUGH of the server's `devVerificationCode`: it renders nothing unless it is given
+ * a non-empty string, and CredentialSignInForm gives it nothing but the value the door returned. There is no environment flag in the
+ * app, so a production IdP (echo off, field absent) can never make it appear.
+ */
+export function DevCodeNotice({ code }: { code?: string | null }) {
+  if (typeof code !== 'string' || code === '') return null;
+  return (
+    <p data-testid="dev-sign-in-code" className="text-sm mt-3" style={{ color: 'var(--text-muted, #6b7280)' }}>
+      Development sign-in code: <strong>{code}</strong>
+    </p>
+  );
+}

package/src/lib/credential-sign-in-client.ts

@@ -22,7 +22,7 @@ export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>
 
 export type CredentialSignInResult =
   | { kind: 'success' }
-  | { kind: 'two_factor'; codeRequest: CodeRequest }
+  | { kind: 'two_factor'; codeRequest: CodeRequest; devCode: string | null }
   | { kind: 'rate_limited'; message: string }
   | { kind: 'error'; message: string; offerEmailCode: boolean };
 
@@ -46,6 +46,11 @@ export function validateCredentials(email: string, password: string): { email?:
   return errors.email || errors.password ? errors : null;
 }
 
+/** The dev echo: the door passes the IdP's DevVerificationCode through as `devVerificationCode`. Nothing else is ever a dev code. */
+function readDevCode(body: any): string | null {
+  return typeof body?.devVerificationCode === 'string' && body.devVerificationCode ? body.devVerificationCode : null;
+}
+
 function asString(v: unknown): string | undefined {
   return typeof v === 'string' && v ? v : undefined;
 }
@@ -64,7 +69,7 @@ export async function credentialSignIn(
     const body: any = await res.json().catch(() => null);
 
     if (res.status === 429) return { kind: 'rate_limited', message: asString(body?.error) ?? MSG_RATE_LIMITED };
-    if (body?.requiresTwoFactor) return { kind: 'two_factor', codeRequest: readCodeRequest(body) };
+    if (body?.requiresTwoFactor) return { kind: 'two_factor', codeRequest: readCodeRequest(body), devCode: readDevCode(body) };
     if (!res.ok || body?.success !== true) {
       return { kind: 'error', message: asString(body?.error) ?? MSG_CANNOT_SIGN_IN, offerEmailCode: body?.offerEmailCode === true };
     }
@@ -89,7 +94,7 @@ export async function requestEmailCode(fetchImpl: FetchLike = (input, init) => f
       return {
         kind: 'requested',
         codeRequest: readCodeRequest(body),
-        devCode: typeof body?.devVerificationCode === 'string' && body.devVerificationCode ? body.devVerificationCode : null,
+        devCode: readDevCode(body),
       };
     }
     return { kind: 'error', message: asString(body?.error) ?? MSG_EMAIL_CODE_FAILED };