@monotykamary/dsh-authorization 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/credentials/authorization/README.md
+README.md: e004bf871b6fe88e087076c9290ff89c8b89396a
+README.zh.md: 0f14ffd52dc3f31ab2109de020dee7623b108323

package/README.md

@@ -0,0 +1,76 @@
+# dsh-authorization
+
+English | [中文](README.zh.md)
+
+Authorization Service Definition (`ctx.authorization`). Some credentials cannot be configured, only obtained: getting one means a conversation with a human — open this page, paste that code, pick an account. This seam owns that conversation and the lifecycle around it, and never the protocol.
+
+**A flow is a plugin's knowledge of how to get its own credential.** It is registered under the [`CredentialKey`](../credentials/README.md#two-key-spaces-two-questions) it writes, so a flow says which record it produces and, through that key's scope, which plugin answers for the format inside it. A second authorization protocol arrives as another flow, not as another seam.
+
+**The flow owns the write.** `run()` resolving means the record is already committed through `ctx.credentials`; the seam confirms a commit it observed during the attempt — presence alone would let a re-authorization pass a stale record off as fresh — and refuses a flow that resolved without one. Committing inside the flow is what lets a library that persists through its own store adapter stay the single writer instead of being copied back out and written twice.
+
+**The interaction travels with the request, not a registry.** Whoever starts an authorization is the one who can talk to the human about it, so prompts reach exactly the surface that asked and a headless caller supplies an interaction that declines. There is no ambient provider to be absent, and no question about which of two open pages a prompt belongs to.
+
+## Surface
+
+```ts
+import type { Context } from '@monotykamary/cordis'
+import { AuthorizationDeclinedError, type AuthorizationSession } from '@monotykamary/dsh-authorization'
+import { credentialKey } from '@monotykamary/dsh-credentials'
+
+declare const ctx: Context
+declare const exchange: (signal: AbortSignal) => Promise<void>
+
+const key = credentialKey('llm-pi-ai', 'openai-codex')
+
+const dispose = ctx.authorization.registerFlow({
+  key,
+  label: 'ChatGPT (Codex)',
+  methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }],
+  async run(session: AuthorizationSession) {
+    session.notify({ message: 'Continue in your browser', url: 'https://auth.example/start' })
+    const code = await session.prompt({ kind: 'text', message: 'Paste the code' })
+    // Commits the record through ctx.credentials before resolving.
+    await exchange(session.signal)
+    void code
+  },
+})
+
+ctx.authorization.list()                    // [{ key, label, methods, inFlight }]
+ctx.authorization.describe(key)             // the same entry, or undefined
+await ctx.authorization.begin({             // { status: 'authorized' | 'cancelled' }
+  key,
+  interaction: { notify: () => {}, prompt: () => Promise.reject(new AuthorizationDeclinedError()) },
+})
+ctx.authorization.cancel(key)               // withdraw whatever is running for the key
+dispose()
+```
+
+One attempt per key at a time. A second caller is refused with `ALREADY_IN_FLIGHT` rather than joined, because the two would be prompting different humans through one flow and the second would be answering questions the first was asked. `inFlight` is on the entry so a surface renders the button disabled instead of discovering this by error.
+
+`cancel(key)` exists beside the request's own signal because a request/response transport answers a Cancel button on a second call, holding no handle on the first one's signal. A flow whose registration is disposed mid-attempt is withdrawn the same way: its runner belongs to a plugin that is going away.
+
+An attempt whose caller has already withdrawn never claims the key and never starts the flow — relying on each flow to check its signal before the first await would let one that does not hang holding the key. Validation still runs first, so a caller naming a key or method that does not exist hears about it whether or not it also gave up.
+
+A human's "no" is an outcome, not a breakage. An interaction that declines rejects its prompt with `AuthorizationDeclinedError`, and an attempt that fails after a declined prompt settles as `cancelled`, exactly as a withdrawn signal does; any other prompt rejection stays a flow failure that reaches the caller. A notice is fire-and-forget on the same principle, held at the seam: a surface that cannot render one loses the notice, never the attempt.
+
+`authorization/settled (key, settlement)` fires after the key is released, for every terminal outcome. `settlement` adds `failed` to the two statuses `begin()` can return: a failure reaches its own caller as a thrown error, so the event stream is the only place a watcher that did not start the attempt can tell a refusal from a breakage. Listener failures are contained: every listener runs, a throw or rejection is logged without changing the finished attempt's outcome, and only an `INVARIANT`-coded failure rethrows after the rest ran.
+
+## The interaction vocabulary
+
+A notice is one-way and never carries a secret: a message, optionally the page the human must open and the code they must enter there. A prompt is a question the flow cannot answer — `text`, `secret`, or `select` — and `secret` differs from `text` only in presentation. A prompt carries its own `signal` so a flow that races a typed code against a browser callback can withdraw the losing question while the attempt continues; the request's signal withdraws the whole attempt instead.
+
+The vocabulary is deliberately smaller than any one provider's: it describes what a surface must render, so a surface that renders one flow renders all of them.
+
+## Model Experience
+
+None, as authorization is a configuration-time conversation with a human and no flow, notice, or prompt reaches a model request.
+
+#### KV Cache effect
+
+No invalidation; no authorization state enters a request prefix.
+
+## Known Limitations and Deferred Work
+
+- **No flow is resumable** — an attempt lives in the process that started it, so a browser reload during a login abandons it and the human starts over. Durable attempts need a store this seam does not have.
+- **Nothing revokes** — signing out is `ctx.credentials.deleteRecord(key)`, which forgets the local record without telling the issuer. A provider that needs a server-side revoke has no place to declare it yet.
+- **A key with no flow is inert** — the seam reports what is registered, so a record left by an uninstalled plugin can be deleted but not re-authorized. Recognizing that orphan is the caller's join, as it is for [`listRecords()`](../credentials/README.md#surface).

package/README.zh.md

@@ -0,0 +1,76 @@
+# dsh-authorization
+
+[English](README.md) | 中文
+
+授权 Service Definition（`ctx.authorization`）。有些凭据无法配置，只能获取：拿到它意味着与人对话——打开这个页面、粘贴那个码、选一个账号。本 seam 拥有这段对话及其生命周期，但从不拥有协议本身。
+
+**flow 是某个插件"如何取得自己那份凭据"的知识。** 它以自己写入的 [`CredentialKey`](../credentials/README.zh.md#two-key-spaces-two-questions) 注册，因此 flow 声明了自己产出哪条记录，并通过该键的 scope 声明由哪个插件为记录内部的格式负责。第二种授权协议以另一个 flow 的形式到来，而不是另一个 seam。
+
+**写入由 flow 拥有。** `run()` 返回即表示记录已经通过 `ctx.credentials` 提交；seam 核实的是它在本次尝试期间观察到的提交——只看记录存在与否，会让重新授权把陈旧记录冒充成新鲜的——并拒绝那些返回时没提交记录的 flow。让提交发生在 flow 内部，才能使一个通过自有 store 适配器持久化的库保持为唯一写入方，而不是把凭据复制出来再写第二遍。
+
+**交互随请求传入，而非注册表。** 发起授权的一方才是能与人对话的一方，因此提示恰好抵达发问的那个界面，无头调用方则传入一个直接拒绝的交互实现。这样既不存在"环境提供方缺席"的问题，也不会出现某个提示该归两个已打开页面中哪一个的疑问。
+
+## 接口
+
+```ts
+import type { Context } from '@monotykamary/cordis'
+import { AuthorizationDeclinedError, type AuthorizationSession } from '@monotykamary/dsh-authorization'
+import { credentialKey } from '@monotykamary/dsh-credentials'
+
+declare const ctx: Context
+declare const exchange: (signal: AbortSignal) => Promise<void>
+
+const key = credentialKey('llm-pi-ai', 'openai-codex')
+
+const dispose = ctx.authorization.registerFlow({
+  key,
+  label: 'ChatGPT (Codex)',
+  methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }],
+  async run(session: AuthorizationSession) {
+    session.notify({ message: 'Continue in your browser', url: 'https://auth.example/start' })
+    const code = await session.prompt({ kind: 'text', message: 'Paste the code' })
+    // Commits the record through ctx.credentials before resolving.
+    await exchange(session.signal)
+    void code
+  },
+})
+
+ctx.authorization.list()                    // [{ key, label, methods, inFlight }]
+ctx.authorization.describe(key)             // the same entry, or undefined
+await ctx.authorization.begin({             // { status: 'authorized' | 'cancelled' }
+  key,
+  interaction: { notify: () => {}, prompt: () => Promise.reject(new AuthorizationDeclinedError()) },
+})
+ctx.authorization.cancel(key)               // withdraw whatever is running for the key
+dispose()
+```
+
+同一个键同时只允许一次尝试。第二个调用方会收到 `ALREADY_IN_FLIGHT` 拒绝而不是被并入：否则两者会通过同一个 flow 向不同的人发问，而第二个人回答的是问给第一个人的问题。`inFlight` 放在 entry 上，界面据此把按钮渲染为禁用，而不是靠报错才发现。
+
+`cancel(key)` 与请求自带的 signal 并存，是因为请求/响应式传输要用第二次调用来响应"取消"按钮，而它拿不到第一次调用的 signal。注册在尝试进行中被 dispose 的 flow 也以同样方式撤销：它的执行体属于一个正在离开的插件。
+
+调用方在发起前就已撤销的尝试，既不占用该键也不启动 flow——若指望每个 flow 都在首个 await 之前检查自己的 signal，那么没有检查的那个就会占着键一直挂起。校验仍然先执行，因此调用方给出的键或方法不存在时，无论它是否已经放弃都会收到报错。
+
+人的"不"是一种结果，不是故障。选择拒绝的交互实现让 prompt 以 `AuthorizationDeclinedError` 拒绝，在提示被拒之后才失败的尝试以 `cancelled` 结算，与 signal 撤销完全一致；其余任何 prompt 拒绝仍是抵达调用方的 flow 故障。notice 依同一原则即发即忘，并由 seam 兜底：渲染不了 notice 的界面丢掉的是那条 notice，而不是整次尝试。
+
+`authorization/settled (key, settlement)` 在键释放之后触发，覆盖每一种终态。`settlement` 在 `begin()` 能返回的两种状态之外增加了 `failed`：失败以抛出的错误抵达其调用方，因此事件流是未发起该尝试的旁观者唯一能区分"被拒绝"与"出故障"的地方。监听器故障被就地遏制：每个监听器都会执行，抛错或拒绝只记录日志、不改变已结束尝试的结果，仅 `INVARIANT` 编码的故障在其余监听器执行完后重抛。
+
+## 交互词汇
+
+notice 是单向的，且从不携带机密：一条消息，以及可选的"人需要打开的页面"和"需要在该页面输入的码"。prompt 是 flow 无法自答的问题——`text`、`secret` 或 `select`——其中 `secret` 与 `text` 的差别仅在呈现方式。prompt 自带 `signal`，使得一个让手输码与浏览器回调赛跑的 flow 可以在尝试继续的同时撤下落败的那个问题；撤销整次尝试则用请求的 signal。
+
+这套词汇刻意小于任何单个 provider 的词汇：它描述的是界面必须渲染什么，因此能渲染一个 flow 的界面就能渲染全部 flow。
+
+## Model Experience
+
+无，因为授权是配置期与人的对话，flow、notice 与 prompt 都不会抵达模型请求。
+
+#### KV Cache effect
+
+不失效；任何授权状态都不会进入请求前缀。
+
+## Known Limitations and Deferred Work
+
+- **flow 不可恢复** —— 一次尝试只存活于发起它的进程中，因此登录途中刷新浏览器会丢弃它，人需要重来。可持久的尝试需要一个本 seam 并不具备的存储。
+- **没有吊销** —— 登出即 `ctx.credentials.deleteRecord(key)`，它只遗忘本地记录而不通知签发方。需要服务端吊销的 provider 目前无处声明这一点。
+- **没有 flow 的键是惰性的** —— seam 只报告已注册的内容，因此被卸载插件遗留的记录可以删除但无法重新授权。识别这种孤儿记录由调用方自行 join，与 [`listRecords()`](../credentials/README.zh.md#surface) 的情况相同。

package/lib/index.js

@@ -0,0 +1,248 @@
+import { Service } from "@monotykamary/cordis";
+import { HarnessError } from "@monotykamary/dsh-llm";
+//#region lib/types/index.js
+/**
+* Service Definition for the authorization capability seam (`ctx.authorization`):
+* obtaining a credential nobody can supply from configuration alone, because
+* getting it requires a conversation with the human — open this page, paste
+* that code, pick an account.
+*
+* The seam owns the conversation and the lifecycle; it never owns the protocol.
+* A plugin that knows how to obtain its own credential registers a flow keyed
+* by the `CredentialKey` that flow writes, and the flow talks to whatever
+* surface started it through one neutral vocabulary of notices and prompts. So
+* a second authorization protocol arrives as another flow rather than as
+* another seam, and a surface that renders one flow renders all of them.
+*
+* ```ts
+* const dispose = ctx.authorization.registerFlow({
+*   key: credentialKey('llm-pi-ai', 'openai-codex'),
+*   label: 'ChatGPT (Codex)',
+*   methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }],
+*   async run(session) {
+*     session.notify({ message: 'Continue in your browser', url })
+*     await commitThroughCredentials(await exchange(session.signal))
+*   },
+* })
+* ```
+*
+* @module @monotykamary/dsh-authorization
+*/
+/** Stable error taxonomy for authorization failures. */
+var AuthorizationError = class extends HarnessError {
+	constructor(message, code, options) {
+		super(message, code, options);
+		this.name = "AuthorizationError";
+	}
+};
+/**
+* The rejection an {@link AuthorizationInteraction.prompt} uses to say the
+* human declined — dismissed the question, chose not to answer — rather than
+* that the surface broke. An attempt whose flow fails after a prompt was
+* declined settles as `cancelled`, the same outcome as a withdrawn signal,
+* because the human saying no is a refusal, not a breakage. Only a human's
+* "no" may reject with this class: a prompt withdrawn by its own `signal` (a
+* flow retiring the losing question of a race) must reject with something
+* else, or a later genuine failure would be misread as a decline.
+*/
+var AuthorizationDeclinedError = class extends AuthorizationError {
+	constructor(message = "the authorization prompt was declined") {
+		super(message, "DECLINED");
+		this.name = "AuthorizationDeclinedError";
+	}
+};
+/**
+* `ctx.authorization`: a registry of credential-obtaining flows, one attempt at
+* a time per key.
+*/
+var AuthorizationService = class extends Service {
+	/** The commit this seam confirms is a credential-record write, so the store is required, not optional. */
+	static inject = ["credentials"];
+	flows = /* @__PURE__ */ new Map();
+	running = /* @__PURE__ */ new Map();
+	constructor(ctx) {
+		super(ctx, "authorization");
+	}
+	/**
+	* Offer a way to obtain one credential. One flow per key: two plugins
+	* claiming the same key would each write a record in their own format, and
+	* whichever ran last would leave the other reading a payload it cannot parse.
+	*
+	* @param flow - the key it writes, its label, its methods, and its runner.
+	* @returns Disposer that withdraws this flow.
+	* @throws {AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.
+	*/
+	registerFlow(flow) {
+		const dispose = this.ctx.effect(function* () {
+			if (this.flows.has(flow.key)) throw new AuthorizationError(`an authorization flow for "${flow.key}" is already registered`, "DUPLICATE_FLOW");
+			this.flows.set(flow.key, flow);
+			yield () => {
+				this.flows.delete(flow.key);
+				this.running.get(flow.key)?.controller.abort();
+			};
+		}.bind(this), "authorization.registerFlow()");
+		return () => void dispose();
+	}
+	/**
+	* Every registered flow, for a surface listing what can be authorized.
+	* @returns one entry per flow, in registration order.
+	*/
+	list() {
+		return [...this.flows.values()].map((flow) => this.entry(flow));
+	}
+	/**
+	* One registered flow.
+	* @param key - the credential record to ask about.
+	* @returns the entry, or undefined when no flow claims that key.
+	*/
+	describe(key) {
+		const flow = this.flows.get(key);
+		return flow === void 0 ? void 0 : this.entry(flow);
+	}
+	/** The public view of one registered flow. */
+	entry(flow) {
+		return {
+			key: flow.key,
+			label: flow.label,
+			methods: flow.methods,
+			inFlight: this.running.has(flow.key)
+		};
+	}
+	/**
+	* Withdraw the attempt running for a key, if any. Separate from the
+	* request's own signal because a request/response transport answers a Cancel
+	* button on a second call, with no handle on the first one's signal.
+	* @param key - the credential record whose attempt should stop.
+	*/
+	cancel(key) {
+		this.running.get(key)?.controller.abort();
+	}
+	/**
+	* Run one attempt to authorize a key, and report how it ended.
+	*
+	* One attempt per key at a time. A second caller is refused rather than
+	* joined: the two would be prompting different humans through the same flow,
+	* and the second would answer questions the first was asked.
+	*
+	* @param request - the key, the method, the surface, and the cancel signal.
+	* @returns `authorized` once the flow's record is committed during this
+	*   attempt and observed, or `cancelled` when the human declined or the
+	*   caller withdrew.
+	* @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
+	*   `UNKNOWN_METHOD` when the named method is not one the flow offers,
+	*   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
+	*   `NOT_COMMITTED` when the flow resolved without committing a record
+	*   during the attempt.
+	*/
+	async begin(request) {
+		const { key } = request;
+		const flow = this.flows.get(key);
+		if (flow === void 0) throw new AuthorizationError(`no authorization flow is registered for "${key}"`, "NO_FLOW");
+		const method = request.method ?? flow.methods[0].id;
+		if (!flow.methods.some((candidate) => candidate.id === method)) throw new AuthorizationError(`authorization flow for "${key}" offers no method "${method}"`, "UNKNOWN_METHOD");
+		if (this.running.has(key)) throw new AuthorizationError(`an authorization attempt for "${key}" is already running`, "ALREADY_IN_FLIGHT");
+		if (request.signal?.aborted === true) return { status: "cancelled" };
+		const controller = new AbortController();
+		const withdraw = () => {
+			controller.abort(request.signal?.reason);
+		};
+		request.signal?.addEventListener("abort", withdraw, { once: true });
+		this.running.set(key, { controller });
+		let settlement = "failed";
+		try {
+			const outcome = await this.attempt(flow, method, controller.signal, request.interaction);
+			settlement = outcome.status;
+			return outcome;
+		} finally {
+			request.signal?.removeEventListener("abort", withdraw);
+			this.running.delete(key);
+			this.settle(key, settlement);
+		}
+	}
+	/**
+	* Fan `authorization/settled` out with contained listener failures: every
+	* listener runs, and a sync throw or async rejection is logged without
+	* changing the finished attempt's own outcome — except `INVARIANT`-coded
+	* failures, which rethrow after every listener ran. The attempt is already
+	* over and its key released when this fires, so a broken watcher (that
+	* second browser tab) can never turn the caller's settled result into a
+	* failure of its own.
+	*/
+	settle(key, settlement) {
+		let invariantFailure;
+		const args = [
+			"authorization/settled",
+			key,
+			settlement
+		];
+		for (const listener of this.ctx.events.dispatch("emit", args)) try {
+			const returned = listener(key, settlement);
+			if (returned != null && typeof returned.then === "function") Promise.resolve(returned).then(void 0, (error) => {
+				this.warnSettledListenerFailure(key, error);
+			});
+		} catch (error) {
+			if (error?.code === "INVARIANT") {
+				invariantFailure ??= error;
+				continue;
+			}
+			this.warnSettledListenerFailure(key, error);
+		}
+		if (invariantFailure !== void 0) throw invariantFailure;
+	}
+	/** Contained-listener diagnostic shared by the sync and async failure paths. */
+	warnSettledListenerFailure(key, error) {
+		this.ctx.logger.warn("authorization: an authorization/settled listener for \"%s\" failed", key);
+		this.ctx.logger.warn(error);
+	}
+	/** Run the flow, then hold it to its half of the commit contract. */
+	async attempt(flow, method, signal, interaction) {
+		const withdrawn = new Promise((resolve) => {
+			signal.addEventListener("abort", () => {
+				resolve("withdrawn");
+			}, { once: true });
+		});
+		const observed = {
+			declined: false,
+			committed: false
+		};
+		const unwatch = this.ctx.on("credentials/record-updated", (key) => {
+			if (key === flow.key) observed.committed = true;
+		});
+		try {
+			const running = flow.run({
+				method,
+				signal,
+				notify: (notice) => {
+					try {
+						interaction.notify(notice);
+					} catch (error) {
+						this.ctx.logger.warn("authorization: the interaction surface failed to render a notice");
+						this.ctx.logger.warn(error);
+					}
+				},
+				prompt: (prompt) => interaction.prompt(prompt).catch((error) => {
+					if (error instanceof AuthorizationDeclinedError) observed.declined = true;
+					throw error;
+				})
+			});
+			try {
+				if (await Promise.race([running.then(() => "ran"), withdrawn]) === "withdrawn") {
+					running.catch(() => {
+						this.ctx.logger.debug("authorization: withdrawn flow failed after the fact");
+					});
+					return { status: "cancelled" };
+				}
+			} catch (error) {
+				if (signal.aborted || observed.declined) return { status: "cancelled" };
+				throw error;
+			}
+		} finally {
+			unwatch();
+		}
+		if (!observed.committed) throw new AuthorizationError(`authorization flow for "${flow.key}" resolved without committing a credential record in this attempt`, "NOT_COMMITTED");
+		if (!(await this.ctx.credentials.describeRecord(flow.key)).configured) throw new AuthorizationError(`authorization flow for "${flow.key}" deleted its credential record instead of committing one`, "NOT_COMMITTED");
+		return { status: "authorized" };
+	}
+};
+//#endregion
+export { AuthorizationDeclinedError, AuthorizationError, AuthorizationService, AuthorizationService as default };

package/lib/invariant.js

@@ -0,0 +1,36 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@monotykamary/dsh-authorization`.
+* @module @monotykamary/dsh-authorization/invariant
+*/
+const PACKAGE_NAME = "@monotykamary/dsh-authorization";
+/** Cordis companion plugin name. */
+const name = "authorization-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Install the single-flight release contract: `authorization/settled` names a
+* finished attempt, and the seam admits one attempt per key, so the key must
+* already be free when the event fires. A slot still held at settlement is
+* unrecoverable — every later `begin()` for that key is refused as
+* `ALREADY_IN_FLIGHT` until the process restarts — and it is invisible from the
+* outside, because a wedged key looks exactly like a busy one.
+*/
+const install = (ctx, fail) => {
+	ctx.on("authorization/settled", (key) => {
+		const authorization = ctx.get("authorization");
+		if (authorization === void 0) {
+			fail(`authorization/settled for "${key}" emitted without a live authorization service`);
+			return;
+		}
+		if (authorization.describe(key)?.inFlight === true) fail(`authorization/settled for "${key}" left the key in flight, wedging every later attempt`);
+	});
+};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Service Definition for the authorization capability seam (`ctx.authorization`):
+ * obtaining a credential nobody can supply from configuration alone, because
+ * getting it requires a conversation with the human — open this page, paste
+ * that code, pick an account.
+ *
+ * The seam owns the conversation and the lifecycle; it never owns the protocol.
+ * A plugin that knows how to obtain its own credential registers a flow keyed
+ * by the `CredentialKey` that flow writes, and the flow talks to whatever
+ * surface started it through one neutral vocabulary of notices and prompts. So
+ * a second authorization protocol arrives as another flow rather than as
+ * another seam, and a surface that renders one flow renders all of them.
+ *
+ * ```ts
+ * const dispose = ctx.authorization.registerFlow({
+ *   key: credentialKey('llm-pi-ai', 'openai-codex'),
+ *   label: 'ChatGPT (Codex)',
+ *   methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }],
+ *   async run(session) {
+ *     session.notify({ message: 'Continue in your browser', url })
+ *     await commitThroughCredentials(await exchange(session.signal))
+ *   },
+ * })
+ * ```
+ *
+ * @module @monotykamary/dsh-authorization
+ */
+import { Context, Service } from '@monotykamary/cordis';
+import type { CredentialKey } from '@monotykamary/dsh-credentials';
+import { HarnessError } from '@monotykamary/dsh-llm';
+import type { AuthorizationEntry, AuthorizationMethod, AuthorizationNotice, AuthorizationOutcome, AuthorizationPrompt, AuthorizationSettlement } from './types.ts';
+export type { AuthorizationEntry, AuthorizationMethod, AuthorizationNotice, AuthorizationOutcome, AuthorizationPrompt, AuthorizationPromptOption, AuthorizationSettlement, AuthorizationStatus, } from './types.ts';
+declare module '@monotykamary/cordis' {
+    interface Context {
+        authorization: AuthorizationService;
+    }
+    interface Events {
+        /**
+         * One authorization attempt has finished and released its key. Fires for
+         * every terminal outcome, failures included, so a surface watching a key it
+         * did not start (a second browser tab) learns the attempt is over.
+         * @mode emit
+         * @param key - the credential record the finished attempt was authorizing.
+         * @param settlement - how it ended, including the `failed` case its caller sees as a thrown error.
+         */
+        'authorization/settled'(key: CredentialKey, settlement: AuthorizationSettlement): void;
+    }
+}
+/** Stable error taxonomy for authorization failures. */
+export declare class AuthorizationError extends HarnessError {
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/**
+ * The rejection an {@link AuthorizationInteraction.prompt} uses to say the
+ * human declined — dismissed the question, chose not to answer — rather than
+ * that the surface broke. An attempt whose flow fails after a prompt was
+ * declined settles as `cancelled`, the same outcome as a withdrawn signal,
+ * because the human saying no is a refusal, not a breakage. Only a human's
+ * "no" may reject with this class: a prompt withdrawn by its own `signal` (a
+ * flow retiring the losing question of a race) must reject with something
+ * else, or a later genuine failure would be misread as a decline.
+ */
+export declare class AuthorizationDeclinedError extends AuthorizationError {
+    constructor(message?: string);
+}
+/**
+ * What a running flow is given to talk to the human. Every member is scoped to
+ * one attempt: the flow neither knows nor chooses which surface is listening.
+ */
+export interface AuthorizationSession {
+    /** The method id the caller picked, always one this flow declared. */
+    readonly method: string;
+    /** Aborted when the caller withdraws or `cancel()` is called for this key. */
+    readonly signal: AbortSignal;
+    /**
+     * Report progress, or tell the human what to do next. Fire-and-forget: a
+     * surface that cannot render a notice must not stall the flow.
+     * @param notice - the message, and any page or code it refers to.
+     */
+    notify(notice: AuthorizationNotice): void;
+    /**
+     * Ask the human a question the flow cannot answer for itself.
+     * @param prompt - what to ask, and how it should be presented.
+     * @returns what the human typed, or the chosen option's id.
+     * @throws when the human declines, or the prompt's own signal withdraws it.
+     */
+    prompt(prompt: AuthorizationPrompt): Promise<string>;
+}
+/**
+ * A plugin's knowledge of how to obtain one credential. The flow owns the
+ * write: `run()` resolving means the record for `key` is committed through
+ * `ctx.credentials` during that run, which the seam confirms — a commit
+ * observed within the attempt, still present after it — before reporting
+ * success. Committing inside the flow is what lets a library that persists
+ * through its own store adapter (pi-ai's `Models.login()`) stay the single
+ * writer instead of being copied back out and written twice.
+ */
+export interface AuthorizationFlow {
+    /** The credential record this flow writes. Its scope names the owning plugin. */
+    readonly key: CredentialKey;
+    /** User-facing name of what is being authorized. */
+    readonly label: string;
+    /**
+     * The methods offered, most preferred first; a caller naming none gets the
+     * first. Typed non-empty because a flow with nothing to run is a flow that
+     * cannot be begun, and the type says so at the one place flows are written.
+     */
+    readonly methods: readonly [AuthorizationMethod, ...AuthorizationMethod[]];
+    /**
+     * Run one attempt to obtain and commit the credential.
+     * @param session - the chosen method, the cancellation signal, and the interaction callbacks.
+     * @returns once the record is committed.
+     * @throws when the attempt fails or the human declines.
+     */
+    run(session: AuthorizationSession): Promise<void>;
+}
+/**
+ * The surface half of one attempt. Supplied with the request rather than
+ * registered, because the caller that starts an authorization is the one that
+ * can talk to the human about it: prompts reach exactly the page that asked,
+ * and a headless caller supplies an interaction that declines.
+ */
+export interface AuthorizationInteraction {
+    /**
+     * Render a notice from the running flow.
+     * @param notice - the message, and any page or code it refers to.
+     */
+    notify(notice: AuthorizationNotice): void;
+    /**
+     * Put a question to the human and wait.
+     * @param prompt - what to ask, and how it should be presented.
+     * @returns the typed text, or the chosen option's id.
+     * @throws {AuthorizationDeclinedError} when the human declines; any other
+     *   rejection reads as the surface failing, not as an answer.
+     */
+    prompt(prompt: AuthorizationPrompt): Promise<string>;
+}
+/** One request to authorize a key. */
+export interface AuthorizationRequest {
+    /** The credential record to authorize; a flow must be registered for it. */
+    key: CredentialKey;
+    /** Which of the flow's methods to run. Defaults to the flow's first. */
+    method?: string;
+    /** The surface that will render this attempt's notices and prompts. */
+    interaction: AuthorizationInteraction;
+    /** Withdraws the whole attempt. */
+    signal?: AbortSignal;
+}
+/**
+ * `ctx.authorization`: a registry of credential-obtaining flows, one attempt at
+ * a time per key.
+ */
+export declare class AuthorizationService extends Service {
+    /** The commit this seam confirms is a credential-record write, so the store is required, not optional. */
+    static inject: string[];
+    private readonly flows;
+    private readonly running;
+    constructor(ctx: Context);
+    /**
+     * Offer a way to obtain one credential. One flow per key: two plugins
+     * claiming the same key would each write a record in their own format, and
+     * whichever ran last would leave the other reading a payload it cannot parse.
+     *
+     * @param flow - the key it writes, its label, its methods, and its runner.
+     * @returns Disposer that withdraws this flow.
+     * @throws {AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.
+     */
+    registerFlow(flow: AuthorizationFlow): () => void;
+    /**
+     * Every registered flow, for a surface listing what can be authorized.
+     * @returns one entry per flow, in registration order.
+     */
+    list(): readonly AuthorizationEntry[];
+    /**
+     * One registered flow.
+     * @param key - the credential record to ask about.
+     * @returns the entry, or undefined when no flow claims that key.
+     */
+    describe(key: CredentialKey): AuthorizationEntry | undefined;
+    /** The public view of one registered flow. */
+    private entry;
+    /**
+     * Withdraw the attempt running for a key, if any. Separate from the
+     * request's own signal because a request/response transport answers a Cancel
+     * button on a second call, with no handle on the first one's signal.
+     * @param key - the credential record whose attempt should stop.
+     */
+    cancel(key: CredentialKey): void;
+    /**
+     * Run one attempt to authorize a key, and report how it ended.
+     *
+     * One attempt per key at a time. A second caller is refused rather than
+     * joined: the two would be prompting different humans through the same flow,
+     * and the second would answer questions the first was asked.
+     *
+     * @param request - the key, the method, the surface, and the cancel signal.
+     * @returns `authorized` once the flow's record is committed during this
+     *   attempt and observed, or `cancelled` when the human declined or the
+     *   caller withdrew.
+     * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
+     *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
+     *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
+     *   `NOT_COMMITTED` when the flow resolved without committing a record
+     *   during the attempt.
+     */
+    begin(request: AuthorizationRequest): Promise<AuthorizationOutcome>;
+    /**
+     * Fan `authorization/settled` out with contained listener failures: every
+     * listener runs, and a sync throw or async rejection is logged without
+     * changing the finished attempt's own outcome — except `INVARIANT`-coded
+     * failures, which rethrow after every listener ran. The attempt is already
+     * over and its key released when this fires, so a broken watcher (that
+     * second browser tab) can never turn the caller's settled result into a
+     * failure of its own.
+     */
+    private settle;
+    /** Contained-listener diagnostic shared by the sync and async failure paths. */
+    private warnSettledListenerFailure;
+    /** Run the flow, then hold it to its half of the commit contract. */
+    private attempt;
+}
+export default AuthorizationService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,299 @@
+/**
+ * Service Definition for the authorization capability seam (`ctx.authorization`):
+ * obtaining a credential nobody can supply from configuration alone, because
+ * getting it requires a conversation with the human — open this page, paste
+ * that code, pick an account.
+ *
+ * The seam owns the conversation and the lifecycle; it never owns the protocol.
+ * A plugin that knows how to obtain its own credential registers a flow keyed
+ * by the `CredentialKey` that flow writes, and the flow talks to whatever
+ * surface started it through one neutral vocabulary of notices and prompts. So
+ * a second authorization protocol arrives as another flow rather than as
+ * another seam, and a surface that renders one flow renders all of them.
+ *
+ * ```ts
+ * const dispose = ctx.authorization.registerFlow({
+ *   key: credentialKey('llm-pi-ai', 'openai-codex'),
+ *   label: 'ChatGPT (Codex)',
+ *   methods: [{ id: 'oauth', label: 'Sign in with ChatGPT' }],
+ *   async run(session) {
+ *     session.notify({ message: 'Continue in your browser', url })
+ *     await commitThroughCredentials(await exchange(session.signal))
+ *   },
+ * })
+ * ```
+ *
+ * @module @monotykamary/dsh-authorization
+ */
+import { Service } from '@monotykamary/cordis';
+import { HarnessError } from '@monotykamary/dsh-llm';
+/** Stable error taxonomy for authorization failures. */
+export class AuthorizationError extends HarnessError {
+    constructor(message, code, options) {
+        super(message, code, options);
+        this.name = 'AuthorizationError';
+    }
+}
+/**
+ * The rejection an {@link AuthorizationInteraction.prompt} uses to say the
+ * human declined — dismissed the question, chose not to answer — rather than
+ * that the surface broke. An attempt whose flow fails after a prompt was
+ * declined settles as `cancelled`, the same outcome as a withdrawn signal,
+ * because the human saying no is a refusal, not a breakage. Only a human's
+ * "no" may reject with this class: a prompt withdrawn by its own `signal` (a
+ * flow retiring the losing question of a race) must reject with something
+ * else, or a later genuine failure would be misread as a decline.
+ */
+export class AuthorizationDeclinedError extends AuthorizationError {
+    constructor(message = 'the authorization prompt was declined') {
+        super(message, 'DECLINED');
+        this.name = 'AuthorizationDeclinedError';
+    }
+}
+/**
+ * `ctx.authorization`: a registry of credential-obtaining flows, one attempt at
+ * a time per key.
+ */
+export class AuthorizationService extends Service {
+    /** The commit this seam confirms is a credential-record write, so the store is required, not optional. */
+    static inject = ['credentials'];
+    flows = new Map();
+    running = new Map();
+    constructor(ctx) {
+        super(ctx, 'authorization');
+    }
+    /**
+     * Offer a way to obtain one credential. One flow per key: two plugins
+     * claiming the same key would each write a record in their own format, and
+     * whichever ran last would leave the other reading a payload it cannot parse.
+     *
+     * @param flow - the key it writes, its label, its methods, and its runner.
+     * @returns Disposer that withdraws this flow.
+     * @throws {AuthorizationError} code `DUPLICATE_FLOW` when the key is already claimed.
+     */
+    registerFlow(flow) {
+        const dispose = this.ctx.effect(function* () {
+            if (this.flows.has(flow.key)) {
+                throw new AuthorizationError(`an authorization flow for "${flow.key}" is already registered`, 'DUPLICATE_FLOW');
+            }
+            this.flows.set(flow.key, flow);
+            yield () => {
+                this.flows.delete(flow.key);
+                // A flow leaving mid-attempt takes its attempt with it: the runner
+                // belongs to a plugin that is going away, so letting it keep prompting
+                // would outlive the fiber that can answer for it.
+                this.running.get(flow.key)?.controller.abort();
+            };
+        }.bind(this), 'authorization.registerFlow()');
+        return () => void dispose();
+    }
+    /**
+     * Every registered flow, for a surface listing what can be authorized.
+     * @returns one entry per flow, in registration order.
+     */
+    list() {
+        return [...this.flows.values()].map(flow => this.entry(flow));
+    }
+    /**
+     * One registered flow.
+     * @param key - the credential record to ask about.
+     * @returns the entry, or undefined when no flow claims that key.
+     */
+    describe(key) {
+        const flow = this.flows.get(key);
+        return flow === undefined ? undefined : this.entry(flow);
+    }
+    /** The public view of one registered flow. */
+    entry(flow) {
+        return {
+            key: flow.key,
+            label: flow.label,
+            methods: flow.methods,
+            inFlight: this.running.has(flow.key),
+        };
+    }
+    /**
+     * Withdraw the attempt running for a key, if any. Separate from the
+     * request's own signal because a request/response transport answers a Cancel
+     * button on a second call, with no handle on the first one's signal.
+     * @param key - the credential record whose attempt should stop.
+     */
+    cancel(key) {
+        this.running.get(key)?.controller.abort();
+    }
+    /**
+     * Run one attempt to authorize a key, and report how it ended.
+     *
+     * One attempt per key at a time. A second caller is refused rather than
+     * joined: the two would be prompting different humans through the same flow,
+     * and the second would answer questions the first was asked.
+     *
+     * @param request - the key, the method, the surface, and the cancel signal.
+     * @returns `authorized` once the flow's record is committed during this
+     *   attempt and observed, or `cancelled` when the human declined or the
+     *   caller withdrew.
+     * @throws {AuthorizationError} code `NO_FLOW` when nothing claims the key,
+     *   `UNKNOWN_METHOD` when the named method is not one the flow offers,
+     *   `ALREADY_IN_FLIGHT` when an attempt is already running for the key, or
+     *   `NOT_COMMITTED` when the flow resolved without committing a record
+     *   during the attempt.
+     */
+    async begin(request) {
+        const { key } = request;
+        const flow = this.flows.get(key);
+        if (flow === undefined) {
+            throw new AuthorizationError(`no authorization flow is registered for "${key}"`, 'NO_FLOW');
+        }
+        const method = request.method ?? flow.methods[0].id;
+        if (!flow.methods.some(candidate => candidate.id === method)) {
+            throw new AuthorizationError(`authorization flow for "${key}" offers no method "${method}"`, 'UNKNOWN_METHOD');
+        }
+        if (this.running.has(key)) {
+            throw new AuthorizationError(`an authorization attempt for "${key}" is already running`, 'ALREADY_IN_FLIGHT');
+        }
+        // Withdrawn before it began: never claim the slot and never run the flow.
+        // Handing an aborted signal to `run()` would rely on every flow checking it
+        // before its first await, and one that does not would hang holding the key.
+        // Validation still runs first, so a caller naming a key or method that does
+        // not exist hears about it whether or not it also gave up.
+        if (request.signal?.aborted === true)
+            return { status: 'cancelled' };
+        const controller = new AbortController();
+        const withdraw = () => { controller.abort(request.signal?.reason); };
+        request.signal?.addEventListener('abort', withdraw, { once: true });
+        this.running.set(key, { controller });
+        let settlement = 'failed';
+        try {
+            const outcome = await this.attempt(flow, method, controller.signal, request.interaction);
+            settlement = outcome.status;
+            return outcome;
+        }
+        finally {
+            request.signal?.removeEventListener('abort', withdraw);
+            this.running.delete(key);
+            // After the slot is released, so a listener that reacts by starting the
+            // next attempt is not refused by the one that just finished.
+            this.settle(key, settlement);
+        }
+    }
+    /* jscpd:ignore-start -- deliberate symmetry with the credentials seam's
+       commit fan-out (`CredentialProvider`): the contained-dispatch shape is the
+       reviewed listener-lifecycle contract, and extracting it would couple the
+       two seams' event semantics. */
+    /**
+     * Fan `authorization/settled` out with contained listener failures: every
+     * listener runs, and a sync throw or async rejection is logged without
+     * changing the finished attempt's own outcome — except `INVARIANT`-coded
+     * failures, which rethrow after every listener ran. The attempt is already
+     * over and its key released when this fires, so a broken watcher (that
+     * second browser tab) can never turn the caller's settled result into a
+     * failure of its own.
+     */
+    settle(key, settlement) {
+        let invariantFailure;
+        const args = ['authorization/settled', key, settlement];
+        for (const listener of this.ctx.events.dispatch('emit', args)) {
+            try {
+                const returned = listener(key, settlement);
+                if (returned != null && typeof returned.then === 'function') {
+                    void Promise.resolve(returned).then(undefined, (error) => {
+                        this.warnSettledListenerFailure(key, error);
+                    });
+                }
+            }
+            catch (error) {
+                if (error?.code === 'INVARIANT') {
+                    invariantFailure ??= error;
+                    continue;
+                }
+                this.warnSettledListenerFailure(key, error);
+            }
+        }
+        if (invariantFailure !== undefined)
+            throw invariantFailure;
+    }
+    /* jscpd:ignore-end */
+    /** Contained-listener diagnostic shared by the sync and async failure paths. */
+    warnSettledListenerFailure(key, error) {
+        this.ctx.logger.warn('authorization: an authorization/settled listener for "%s" failed', key);
+        this.ctx.logger.warn(error);
+    }
+    /** Run the flow, then hold it to its half of the commit contract. */
+    async attempt(flow, method, signal, interaction) {
+        // Withdrawal settles the attempt whether or not the flow reacts to it. A
+        // flow is supposed to stop when its signal fires, but one that does not
+        // would otherwise hold the key for the life of the process, and a wedged
+        // key is indistinguishable from a busy one from the outside. The orphaned
+        // run is left to finish on its own; nothing waits on it, and a record it
+        // still manages to commit is a record the human did authorize.
+        const withdrawn = new Promise((resolve) => {
+            // `begin()` returns before claiming the key when its caller has already
+            // withdrawn, so this signal cannot already be aborted here.
+            signal.addEventListener('abort', () => { resolve('withdrawn'); }, { once: true });
+        });
+        // What the seam itself witnessed during the run, held as properties
+        // because closure writes do not narrow locals across awaits: the prompt
+        // wrapper sees a decline first-hand (a flow that rewraps the rejection on
+        // its way out cannot hide it), and confirming the commit means confirming
+        // it happened *now* — on a re-auth the record already exists, so presence
+        // alone would let a flow that wrote nothing report the stale credential
+        // as freshly authorized.
+        const observed = { declined: false, committed: false };
+        const unwatch = this.ctx.on('credentials/record-updated', (key) => {
+            if (key === flow.key)
+                observed.committed = true;
+        });
+        try {
+            const running = flow.run({
+                method,
+                signal,
+                notify: (notice) => {
+                    try {
+                        interaction.notify(notice);
+                    }
+                    catch (error) {
+                        // Fire-and-forget is held at the seam: a surface that cannot
+                        // render a notice (a page whose connection just closed) loses the
+                        // notice, never the attempt.
+                        this.ctx.logger.warn('authorization: the interaction surface failed to render a notice');
+                        this.ctx.logger.warn(error);
+                    }
+                },
+                prompt: prompt => interaction.prompt(prompt).catch((error) => {
+                    if (error instanceof AuthorizationDeclinedError)
+                        observed.declined = true;
+                    throw error;
+                }),
+            });
+            try {
+                if (await Promise.race([running.then(() => 'ran'), withdrawn]) === 'withdrawn') {
+                    // Nothing awaits the orphan any more, so its eventual failure has to be
+                    // marked handled or it would take down the process.
+                    void running.catch(() => { this.ctx.logger.debug('authorization: withdrawn flow failed after the fact'); });
+                    return { status: 'cancelled' };
+                }
+            }
+            catch (error) {
+                // A withdrawn attempt and a declined prompt are outcomes, not
+                // failures: the human said no, or closed the page. Anything else is
+                // the flow failing and belongs to the caller, cause chain intact.
+                if (signal.aborted || observed.declined)
+                    return { status: 'cancelled' };
+                throw error;
+            }
+        }
+        finally {
+            unwatch();
+        }
+        if (!observed.committed) {
+            throw new AuthorizationError(`authorization flow for "${flow.key}" resolved without committing a credential record in this attempt`, 'NOT_COMMITTED');
+        }
+        const stored = await this.ctx.credentials.describeRecord(flow.key);
+        if (!stored.configured) {
+            throw new AuthorizationError(`authorization flow for "${flow.key}" deleted its credential record instead of committing one`, 'NOT_COMMITTED');
+        }
+        return { status: 'authorized' };
+    }
+}
+export default AuthorizationService;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@monotykamary/dsh-authorization`.
+ * @module @monotykamary/dsh-authorization/invariant
+ */
+import type { Context } from '@monotykamary/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "authorization-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,38 @@
+/**
+ * Package-owned invariant companion for `@monotykamary/dsh-authorization`.
+ * @module @monotykamary/dsh-authorization/invariant
+ */
+const PACKAGE_NAME = '@monotykamary/dsh-authorization';
+/** Cordis companion plugin name. */
+export const name = 'authorization-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * Install the single-flight release contract: `authorization/settled` names a
+ * finished attempt, and the seam admits one attempt per key, so the key must
+ * already be free when the event fires. A slot still held at settlement is
+ * unrecoverable — every later `begin()` for that key is refused as
+ * `ALREADY_IN_FLIGHT` until the process restarts — and it is invisible from the
+ * outside, because a wedged key looks exactly like a busy one.
+ */
+const install = (ctx, fail) => {
+    ctx.on('authorization/settled', (key) => {
+        const authorization = ctx.get('authorization');
+        if (authorization === undefined) {
+            fail(`authorization/settled for "${key}" emitted without a live authorization service`);
+            return;
+        }
+        // A flow withdrawn during its own attempt settles with nothing left to
+        // describe, which is the disposer's documented behavior rather than a leak.
+        if (authorization.describe(key)?.inFlight === true) {
+            fail(`authorization/settled for "${key}" left the key in flight, wedging every later attempt`);
+        }
+    });
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Wire-safe authorization types, free of cordis/service imports so browser type
+ * chains (apiproxy api → client) can consume them without loading this
+ * package's Context augmentation.
+ * @module @monotykamary/dsh-authorization/types
+ */
+import type { CredentialKey } from '@monotykamary/dsh-credentials/types';
+/** One way a flow can obtain its credential, named by the flow that offers it. */
+export interface AuthorizationMethod {
+    /** Flow-owned identifier, echoed back when a caller picks this method. */
+    id: string;
+    /** User-facing label for a picker. */
+    label: string;
+}
+/** A running flow's report to whoever is watching it. Never carries a secret. */
+export interface AuthorizationNotice {
+    /** What is happening, or what the human must do next. */
+    message: string;
+    /** A page the human must open to continue. */
+    url?: string;
+    /** A short code the human must enter on that page. */
+    code?: string;
+}
+/** One choice offered by a `select` prompt. */
+export interface AuthorizationPromptOption {
+    /** Value returned when this option is chosen. */
+    id: string;
+    /** User-facing label. */
+    label: string;
+    /** Optional extra context rendered by capable surfaces. */
+    description?: string;
+}
+/**
+ * A question a flow must have answered before it can continue. `secret` differs
+ * from `text` only in presentation — a surface masks it and keeps it out of
+ * logs — and `select` answers with the chosen option's `id`.
+ */
+export type AuthorizationPrompt = {
+    /**
+     * Withdraws this prompt alone, leaving the flow running. A flow that races a
+     * typed code against a browser callback aborts the losing prompt here; the
+     * whole authorization is cancelled through the request's signal instead.
+     */
+    signal?: AbortSignal;
+} & ({
+    kind: 'text';
+    message: string;
+    placeholder?: string;
+} | {
+    kind: 'secret';
+    message: string;
+    placeholder?: string;
+} | {
+    kind: 'select';
+    message: string;
+    options: readonly AuthorizationPromptOption[];
+});
+/** How one authorization attempt ended, as its own caller sees it. */
+export type AuthorizationStatus = 'authorized' | 'cancelled';
+/**
+ * How one attempt ended, as an onlooker sees it. A failure reaches its caller
+ * as a thrown error rather than an outcome, so `failed` exists only here — on
+ * the event stream, where a watcher that did not start the attempt has no
+ * other way to tell a refusal from a breakage.
+ */
+export type AuthorizationSettlement = AuthorizationStatus | 'failed';
+/** The result of one `begin()` attempt. */
+export interface AuthorizationOutcome {
+    /** `authorized` once the record is committed and observed; `cancelled` when the human or caller withdrew. */
+    status: AuthorizationStatus;
+}
+/** A registered flow as a surface sees it: what it authorizes and whether it is busy. */
+export interface AuthorizationEntry {
+    /** The credential record this flow writes. */
+    key: CredentialKey;
+    /** User-facing name of what is being authorized. */
+    label: string;
+    /** The methods this flow offers, most preferred first. */
+    methods: readonly AuthorizationMethod[];
+    /** Whether an attempt for this key is running right now. */
+    inFlight: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,8 @@
+/**
+ * Wire-safe authorization types, free of cordis/service imports so browser type
+ * chains (apiproxy api → client) can consume them without loading this
+ * package's Context augmentation.
+ * @module @monotykamary/dsh-authorization/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@monotykamary/dsh-authorization",
+  "description": "Authorization seam (ctx.authorization): plugin-owned flows that obtain a credential through a conversation with the human",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/credentials/authorization"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@monotykamary/dsh-invariants": "^0.1.0",
+    "@monotykamary/dsh-credentials": "^0.1.0",
+    "@monotykamary/dsh-llm": "^0.1.0",
+    "@monotykamary/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@monotykamary/dsh-credentials": "^0.1.0",
+    "@monotykamary/dsh-invariants": "^0.1.0",
+    "@monotykamary/dsh-llm": "^0.1.0",
+    "@monotykamary/cordis": "^4.0.1"
+  }
+}