@hydraharness/harness-credentials 0.1.1-rc.5

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.md

@@ -0,0 +1,68 @@
+# @hydraharness/harness-credentials
+
+Credential Service Definition (`ctx.credentials`). One doctrine, three consequences:
+
+**Configuration carries references to secrets, never the secrets.** A settings section or `cordis.yml` entry says `apiKeyEnv: DEEPSEEK_API_KEY`; the value behind that reference lives with a credential provider. So the settings document stays safe to sync and to render in a configuration UI, `describe()` can answer "is this configured, where from, can I write it" without ever holding a value, and rotating a secret touches no configuration file.
+
+**Consumers resolve per operation.** `resolve(ref)` is called at the start of each operation (the LLM adapters resolve once per model request) and never cached across operations — that read is what makes a changed credential reach the very next request without restarting any plugin.
+
+**An empty stored value is absent.** Everywhere: `resolve` skips it, `describe` reports it unconfigured. A blank can never masquerade as a configured secret.
+
+## Two key spaces, two questions
+
+A `CredentialRef` answers *what is behind this environment-variable name*, layered over the process environment, the managed store, and `.env` files. Everything above describes that half.
+
+A `CredentialKey` answers *what credential does this plugin hold for this id*. Nothing can layer here — an authorization grant has no environment to be read from — so presence of the record is the whole fact, and the empty-value rule does not apply: an `api-key` record carrying neither a key nor environment values states that its owner confirmed ambient authentication, which is configured.
+
+The key is `<scope>/<id>`, where `scope` is the **owning plugin's registered name**. The scope is the owner rather than the domain because a `grant` payload is written in its owner's format: two plugins serving the same provider name would otherwise read each other's payload, and a record left behind by an uninstalled plugin could not be told apart from a live one. The `/` also keeps the two grammars disjoint, so the key spaces can never collide. A consumer whose id arrives from somewhere else — a settings dict key, a library's own provider id — asks `isCredentialKeySegment` before building a key, because an id outside the grammar can never have stored a record and should read as "nothing stored" rather than throw on the address.
+
+## Surface
+
+```ts
+import type { Context } from '@hydraharness/cordis'
+import { credentialKey, credentialRef } from '@hydraharness/harness-credentials'
+
+declare const ctx: Context
+
+const ref = credentialRef('DEEPSEEK_API_KEY')            // POSIX shell identifier, branded
+const hit = await ctx.credentials.resolve(ref)           // { value, source } | undefined
+const info = await ctx.credentials.describe(ref)         // { configured, source?, writable } — never the value
+await ctx.credentials.set(ref, 'sk-…')                   // rejects while a read-only source shadows the ref
+await ctx.credentials.unset(ref)                         // no-op when absent; same shadowing rule
+
+const key = credentialKey('llm-pi-ai', 'openai-codex')   // <owner>/<id>, branded
+await ctx.credentials.readRecord(key)                    // CredentialRecord | undefined
+await ctx.credentials.describeRecord(key)                // { configured, kind?, writable } — never the value
+await ctx.credentials.listRecords()                      // [{ key, kind }] — never values
+await ctx.credentials.modifyRecord(key, async () => ({ kind: 'grant', payload: { token: '…' } }))
+await ctx.credentials.deleteRecord(key)                  // no-op when absent
+```
+
+`modifyRecord` is the only write path because a correct write depends on the current value: a token refresh is read-decide-replace, and the mutation must see the record as it stands at the moment the write is exclusive. Exclusion holds across processes, which is what stops two of them rotating one refresh token and losing whichever wrote first. Returning `undefined` from the mutation leaves the entry untouched and announces nothing.
+
+`listRecords` exists even though the reference half has no enumeration by design. References are discovered from settings schemas (`apiKeyEnv` fields); records have no such path, so a surface that cannot list them cannot show what a user is authorized for, nor find an orphan left by an uninstalled plugin.
+
+A `grant` record's `payload` is opaque: the seam never reads, validates, or reshapes it. The one constraint is that it survives a JSON round trip, which the provider enforces on the way in and on the way out — a value the store could not read back exactly as written is refused rather than stored lossily.
+
+`credentials/reference-updated (ref)` fires after a committed change to a provider-managed source — a `set`, an `unset`, or an external edit observed in storage. Ambient process-environment changes are not observable and never emit. Consumers do not need the event (they re-resolve per operation); it exists for configuration UIs refreshing a "configured" badge. Its declaration lives in the client-safe `./types` subpath export together with the `CredentialRef` type it names (the package root re-exports the type), so a consumer outside the Host compilation face reads the very signature the Host emits instead of restating it.
+
+The shadowing rule on `set`/`unset` is deliberate fail-loud: when a read-only source (the live process environment, in the local provider) currently supplies the reference, a write would appear to succeed while resolution keeps returning the shadowing value — the seam rejects instead, and `describe().writable` lets a UI render the reference read-only up front.
+
+## Providers
+
+[`@hydraharness/harness-credentials-local`](../credentials-local/README.md) layers the inherited process environment over its managed `$HYDRA_HOME/.credentials.yaml` document, with the launcher's project and user `.env` layers as fallbacks. The seam shape leaves room for keyring-, helper-command-, and KMS-backed providers; a remote settings provider never needs to carry secrets.
+
+## Model Experience
+
+Indirectly, through the consuming LLM adapters: a resolved value authorizes their provider requests, and the adapter owns every model-visible surface.
+
+#### KV Cache effect
+
+No direct invalidation; credentials never enter a request prefix.
+
+## Known Limitations and Deferred Work
+
+- **References have no enumeration** — the seam answers questions about references it is given; configuration surfaces learn them from settings schemas, so a `list()` over that half has no current consumer. Records do enumerate, for the reason above.
+- **References are environment-variable-shaped** — one flat POSIX-identifier namespace, because a reference doubles as the environment name it resolves through. Records carry the richer `<owner>/<id>` addressing.
+- **Process-environment changes are invisible** — no event can fire for them; a UI only re-reads `describe()` on its own navigation.
+- **A record's owner is its scope, and nothing verifies the scope is mounted** — the seam stores what it is given and reports what it stores. Recognizing an orphan is the caller's join between `listRecords()` and whatever registry owns that scope; the seam has no registry of its own to check against.

package/lib/index.js

@@ -0,0 +1,158 @@
+import { Service } from "@hydraharness/cordis";
+//#region lib/types/index.js
+/**
+* Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
+* *references* to secrets — environment-variable names — while providers own
+* the actual values and their storage. Consumers resolve a reference once per
+* operation, so a changed credential reaches the next operation without any
+* plugin restart, and configuration surfaces describe a reference without
+* ever seeing its value.
+* @module @hydraharness/harness-credentials
+*/
+const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Both halves of a {@link CredentialKey}; the `/` between them is what keeps it out of {@link REF_PATTERN}. */
+const KEY_SEGMENT_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+* Brand a raw string as a {@link CredentialRef}.
+* @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
+* @returns the branded reference.
+*/
+function credentialRef(value) {
+	if (!isCredentialRefName(value)) throw new TypeError(`credential ref "${value}" must match ${String(REF_PATTERN)}`);
+	return value;
+}
+/**
+* Whether a raw string could name a reference at all. Consumers that receive
+* environment-variable names from somewhere else — a provider library's own
+* ambient discovery, a hook payload — ask this before resolving, because a name
+* outside the grammar has no reference to miss and should read as "not set"
+* rather than as a thrown error.
+* @param value - candidate reference.
+* @returns true when {@link credentialRef} would accept it.
+*/
+function isCredentialRefName(value) {
+	return REF_PATTERN.test(value);
+}
+/**
+* Whether a raw string could be a {@link credentialKey} segment at all.
+* Consumers whose addressing units come from somewhere else — a settings dict
+* key, a library's own provider id — ask this before building a key, because a
+* unit outside the grammar can never have stored a record and should read as
+* "nothing stored" rather than as a thrown error.
+* @param value - candidate segment.
+* @returns true when {@link credentialKey} would accept it as either segment.
+*/
+function isCredentialKeySegment(value) {
+	return KEY_SEGMENT_PATTERN.test(value);
+}
+/**
+* Brand a scope and an id as a {@link CredentialKey}.
+* @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
+* @param id - that plugin's own addressing unit, such as a provider route key.
+* @returns the branded key.
+* @throws TypeError when either segment is not a lowercase hyphenated identifier.
+*/
+function credentialKey(scope, id) {
+	for (const segment of [scope, id]) if (!KEY_SEGMENT_PATTERN.test(segment)) throw new TypeError(`credential key segment "${segment}" must match ${String(KEY_SEGMENT_PATTERN)}`);
+	return `${scope}/${id}`;
+}
+/**
+* Brand a stored `<scope>/<id>` string as a {@link CredentialKey}. This is the
+* read half of {@link credentialKey}, for a provider admitting keys off disk.
+* @param value - candidate key in its joined form.
+* @returns the branded key.
+* @throws TypeError when the value is not exactly two valid segments.
+*/
+function parseCredentialKey(value) {
+	const segments = value.split("/");
+	const [scope, id] = segments;
+	if (segments.length !== 2 || scope === void 0 || id === void 0) throw new TypeError(`credential key "${value}" must be "<scope>/<id>"`);
+	return credentialKey(scope, id);
+}
+/**
+* The owning plugin's name for one key. A record whose scope names no
+* currently registered owner is an orphan, which a configuration surface must
+* report as such rather than as a working credential.
+* @param key - the key to read.
+* @returns the scope segment.
+*/
+function credentialKeyScope(key) {
+	return key.slice(0, key.indexOf("/"));
+}
+/**
+* The owning plugin's own addressing unit for one key — the half that plugin
+* chose, such as a provider route.
+* @param key - the key to read.
+* @returns the id segment.
+*/
+function credentialKeyId(key) {
+	return key.slice(key.indexOf("/") + 1);
+}
+/**
+* Abstract credential service over two key spaces that answer two questions.
+*
+* A {@link CredentialRef} answers "what is behind this environment-variable
+* name", layered over the process environment, the provider-managed store, and
+* `.env` files. One seam-wide rule binds that half: an empty stored value is
+* absent everywhere — `resolve` skips it, `describe` reports it unconfigured —
+* so a blank never masquerades as a configured secret.
+*
+* A {@link CredentialKey} answers "what credential does this plugin hold for
+* this id". Nothing can layer here — an authorization grant has no
+* environment to be read from — so presence of the record is the whole fact,
+* and {@link modifyRecord} is the only write path because a correct write
+* depends on the current value (a token refresh is read-decide-replace under
+* one lock).
+*/
+var CredentialProvider = class extends Service {
+	constructor(ctx) {
+		super(ctx, "credentials");
+	}
+	/**
+	* Fan `credentials/reference-updated` out with contained listener failures: every
+	* listener runs, and a sync throw or async rejection is logged without
+	* changing the committed operation's outcome — except `INVARIANT`-coded
+	* failures, which rethrow after every listener ran (the rethrow reaches the
+	* caller only from synchronous listeners, so invariant checks on this event
+	* must not be async functions). Providers call this only after the write or
+	* reload actually committed, so a broken observer can never make a durable
+	* change look failed.
+	* @param ref - the reference whose stored value changed.
+	*/
+	notifyUpdated(ref) {
+		this.fanOut("credentials/reference-updated", ref);
+	}
+	/**
+	* Fan `credentials/record-updated` out on exactly the terms
+	* {@link notifyUpdated} documents, for the record half of the seam.
+	* @param key - the record whose stored value changed.
+	*/
+	notifyRecordUpdated(key) {
+		this.fanOut("credentials/record-updated", key);
+	}
+	/** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
+	fanOut(event, subject) {
+		let invariantFailure;
+		const args = [event, subject];
+		for (const listener of this.ctx.events.dispatch("emit", args)) try {
+			const returned = listener(subject);
+			if (returned != null && typeof returned.then === "function") Promise.resolve(returned).then(void 0, (error) => {
+				this.warnListenerFailure(event, subject, error);
+			});
+		} catch (error) {
+			if (error?.code === "INVARIANT") {
+				invariantFailure ??= error;
+				continue;
+			}
+			this.warnListenerFailure(event, subject, error);
+		}
+		if (invariantFailure !== void 0) throw invariantFailure;
+	}
+	/** Contained-listener diagnostic shared by the sync and async failure paths. */
+	warnListenerFailure(event, subject, error) {
+		this.ctx.logger.warn("credentials: a %s listener for \"%s\" failed", event, subject);
+		this.ctx.logger.warn(error);
+	}
+};
+//#endregion
+export { CredentialProvider, CredentialProvider as default, credentialKey, credentialKeyId, credentialKeyScope, credentialRef, isCredentialKeySegment, isCredentialRefName, parseCredentialKey };

package/lib/invariant.js

@@ -0,0 +1,31 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-credentials`.
+* @module @hydraharness/harness-credentials/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-credentials";
+/** Cordis companion plugin name. */
+const name = "credentials-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Install the commit-event lifecycle contract: `credentials/reference-updated` names a
+* committed provider-source change, so it can only fire while a credentials
+* service is live — an emission after disposal means a provider leaked work
+* past its teardown quiescence. The value relation itself (`describe`
+* agreeing with `resolve`) is asynchronous provider I/O and stays pinned by
+* each provider's own suite.
+*/
+const install = (ctx, fail) => {
+	ctx.on("credentials/reference-updated", (ref) => {
+		if (ctx.get("credentials") === void 0) fail(`credentials/reference-updated for "${ref}" emitted without a live credentials service`);
+	});
+};
+/**
+* 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,225 @@
+/**
+ * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
+ * *references* to secrets — environment-variable names — while providers own
+ * the actual values and their storage. Consumers resolve a reference once per
+ * operation, so a changed credential reaches the next operation without any
+ * plugin restart, and configuration surfaces describe a reference without
+ * ever seeing its value.
+ * @module @hydraharness/harness-credentials
+ */
+import { Context, Service } from '@hydraharness/cordis';
+import type { CredentialKey, CredentialRecord, CredentialRef } from './types.ts';
+export type { ApiKeyRecord, CredentialKey, CredentialRecord, CredentialRef, GrantRecord } from './types.ts';
+/**
+ * Brand a raw string as a {@link CredentialRef}.
+ * @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
+ * @returns the branded reference.
+ */
+export declare function credentialRef(value: string): CredentialRef;
+/**
+ * Whether a raw string could name a reference at all. Consumers that receive
+ * environment-variable names from somewhere else — a provider library's own
+ * ambient discovery, a hook payload — ask this before resolving, because a name
+ * outside the grammar has no reference to miss and should read as "not set"
+ * rather than as a thrown error.
+ * @param value - candidate reference.
+ * @returns true when {@link credentialRef} would accept it.
+ */
+export declare function isCredentialRefName(value: string): boolean;
+/**
+ * Whether a raw string could be a {@link credentialKey} segment at all.
+ * Consumers whose addressing units come from somewhere else — a settings dict
+ * key, a library's own provider id — ask this before building a key, because a
+ * unit outside the grammar can never have stored a record and should read as
+ * "nothing stored" rather than as a thrown error.
+ * @param value - candidate segment.
+ * @returns true when {@link credentialKey} would accept it as either segment.
+ */
+export declare function isCredentialKeySegment(value: string): boolean;
+/**
+ * Brand a scope and an id as a {@link CredentialKey}.
+ * @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
+ * @param id - that plugin's own addressing unit, such as a provider route key.
+ * @returns the branded key.
+ * @throws TypeError when either segment is not a lowercase hyphenated identifier.
+ */
+export declare function credentialKey(scope: string, id: string): CredentialKey;
+/**
+ * Brand a stored `<scope>/<id>` string as a {@link CredentialKey}. This is the
+ * read half of {@link credentialKey}, for a provider admitting keys off disk.
+ * @param value - candidate key in its joined form.
+ * @returns the branded key.
+ * @throws TypeError when the value is not exactly two valid segments.
+ */
+export declare function parseCredentialKey(value: string): CredentialKey;
+/**
+ * The owning plugin's name for one key. A record whose scope names no
+ * currently registered owner is an orphan, which a configuration surface must
+ * report as such rather than as a working credential.
+ * @param key - the key to read.
+ * @returns the scope segment.
+ */
+export declare function credentialKeyScope(key: CredentialKey): string;
+/**
+ * The owning plugin's own addressing unit for one key — the half that plugin
+ * chose, such as a provider route.
+ * @param key - the key to read.
+ * @returns the id segment.
+ */
+export declare function credentialKeyId(key: CredentialKey): string;
+/** One resolved credential value and the source layer that supplied it. */
+export interface ResolvedCredential {
+    /** The non-empty secret value. */
+    value: string;
+    /** Provider-defined source layer id (the local provider uses `env`, `file`, `project-env`, and `user-env`). */
+    source: string;
+}
+/** Source and writability facts for one reference, safe for configuration UIs — never the value. */
+export interface CredentialInfo {
+    /** Whether {@link CredentialProvider.resolve} would currently return a value. */
+    configured: boolean;
+    /** Source layer currently supplying the value; absent while unconfigured. */
+    source?: string;
+    /** Whether {@link CredentialProvider.set} would currently succeed for this reference. */
+    writable: boolean;
+}
+/** Presence and writability facts for one record, safe for configuration UIs — never the value. */
+export interface CredentialRecordInfo {
+    /**
+     * Whether a record is stored. Unlike a reference, presence alone answers
+     * this: an {@link ApiKeyRecord} carrying neither a key nor environment
+     * values states that its owner confirmed ambient authentication, which is
+     * configured, not blank.
+     */
+    configured: boolean;
+    /** Discriminant of the stored record; absent while none is stored. */
+    kind?: CredentialRecord['kind'];
+    /** Whether {@link CredentialProvider.modifyRecord} would currently succeed. */
+    writable: boolean;
+}
+/** One stored record's address and tag, for enumeration — never its value. */
+export interface CredentialRecordEntry {
+    /** The record's address. */
+    key: CredentialKey;
+    /** Discriminant of the stored record. */
+    kind: CredentialRecord['kind'];
+}
+declare module '@hydraharness/cordis' {
+    interface Context {
+        credentials: CredentialProvider;
+    }
+}
+/**
+ * Abstract credential service over two key spaces that answer two questions.
+ *
+ * A {@link CredentialRef} answers "what is behind this environment-variable
+ * name", layered over the process environment, the provider-managed store, and
+ * `.env` files. One seam-wide rule binds that half: an empty stored value is
+ * absent everywhere — `resolve` skips it, `describe` reports it unconfigured —
+ * so a blank never masquerades as a configured secret.
+ *
+ * A {@link CredentialKey} answers "what credential does this plugin hold for
+ * this id". Nothing can layer here — an authorization grant has no
+ * environment to be read from — so presence of the record is the whole fact,
+ * and {@link modifyRecord} is the only write path because a correct write
+ * depends on the current value (a token refresh is read-decide-replace under
+ * one lock).
+ */
+export declare abstract class CredentialProvider extends Service {
+    constructor(ctx: Context);
+    /**
+     * Resolve one reference to its current value. Resolution is per call:
+     * consumers re-resolve at each operation and must not cache across
+     * operations — that per-operation read is what makes a changed credential
+     * reach the next operation without a restart.
+     * @param ref - the reference to resolve.
+     * @returns the value and its source, or `undefined` while unconfigured.
+     */
+    abstract resolve(ref: CredentialRef): Promise<ResolvedCredential | undefined>;
+    /**
+     * Describe one reference for configuration surfaces without exposing the
+     * value.
+     * @param ref - the reference to describe.
+     * @returns configured state, supplying source, and writability.
+     */
+    abstract describe(ref: CredentialRef): Promise<CredentialInfo>;
+    /**
+     * Durably store one value in the provider-managed writable source. Rejects
+     * while a read-only source shadows the reference — the write would appear
+     * to succeed while resolution keeps returning the shadowing value — and
+     * rejects an empty value (use {@link unset}).
+     * @param ref - the reference to store.
+     * @param value - the non-empty secret value.
+     */
+    abstract set(ref: CredentialRef, value: string): Promise<void>;
+    /**
+     * Remove one reference from the provider-managed writable source; removing
+     * an absent reference is a no-op. Rejects while a read-only source shadows
+     * the reference, like {@link set}.
+     * @param ref - the reference to remove.
+     */
+    abstract unset(ref: CredentialRef): Promise<void>;
+    /**
+     * Read one stored record. The value is returned as its owner wrote it; a
+     * {@link GrantRecord} payload is not interpreted on the way out.
+     * @param key - the record to read.
+     * @returns the record, or `undefined` while none is stored.
+     */
+    abstract readRecord(key: CredentialKey): Promise<CredentialRecord | undefined>;
+    /**
+     * Describe one record for configuration surfaces without exposing its value.
+     * @param key - the record to describe.
+     * @returns presence, discriminant, and writability.
+     */
+    abstract describeRecord(key: CredentialKey): Promise<CredentialRecordInfo>;
+    /**
+     * Enumerate every stored record's address and tag. Unlike the reference
+     * half, which has no enumeration because configuration surfaces learn which
+     * references exist from settings schemas, records have no such discovery
+     * path: a surface that cannot list them cannot show what a user is
+     * authorized for, nor find an orphan left by an uninstalled plugin.
+     * @returns every stored record, values excluded.
+     */
+    abstract listRecords(): Promise<readonly CredentialRecordEntry[]>;
+    /**
+     * Serialized read-modify-write over one record — the only write path.
+     * `mutate` sees the record as it stands at the moment the write is
+     * exclusive, and returning `undefined` leaves the entry untouched. Exclusion
+     * holds across processes where the backing store supports it, which is what
+     * makes a token refresh safe: two processes rotating one refresh token
+     * concurrently would otherwise lose whichever wrote first.
+     * @param key - the record to modify.
+     * @param mutate - receives the current record and returns its replacement, or `undefined` to leave it.
+     * @returns the record after the write, or the current one when `mutate` declined.
+     */
+    abstract modifyRecord(key: CredentialKey, mutate: (current: CredentialRecord | undefined) => Promise<CredentialRecord | undefined>): Promise<CredentialRecord | undefined>;
+    /**
+     * Remove one record; removing an absent record is a no-op.
+     * @param key - the record to remove.
+     */
+    abstract deleteRecord(key: CredentialKey): Promise<void>;
+    /**
+     * Fan `credentials/reference-updated` out with contained listener failures: every
+     * listener runs, and a sync throw or async rejection is logged without
+     * changing the committed operation's outcome — except `INVARIANT`-coded
+     * failures, which rethrow after every listener ran (the rethrow reaches the
+     * caller only from synchronous listeners, so invariant checks on this event
+     * must not be async functions). Providers call this only after the write or
+     * reload actually committed, so a broken observer can never make a durable
+     * change look failed.
+     * @param ref - the reference whose stored value changed.
+     */
+    protected notifyUpdated(ref: CredentialRef): void;
+    /**
+     * Fan `credentials/record-updated` out on exactly the terms
+     * {@link notifyUpdated} documents, for the record half of the seam.
+     * @param key - the record whose stored value changed.
+     */
+    protected notifyRecordUpdated(key: CredentialKey): void;
+    /** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
+    private fanOut;
+    /** Contained-listener diagnostic shared by the sync and async failure paths. */
+    private warnListenerFailure;
+}
+export default CredentialProvider;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,177 @@
+/**
+ * Service Definition for the credential-reference capability seam (`ctx.credentials`). Settings and composition files carry
+ * *references* to secrets — environment-variable names — while providers own
+ * the actual values and their storage. Consumers resolve a reference once per
+ * operation, so a changed credential reaches the next operation without any
+ * plugin restart, and configuration surfaces describe a reference without
+ * ever seeing its value.
+ * @module @hydraharness/harness-credentials
+ */
+import { Service } from '@hydraharness/cordis';
+const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Both halves of a {@link CredentialKey}; the `/` between them is what keeps it out of {@link REF_PATTERN}. */
+const KEY_SEGMENT_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Brand a raw string as a {@link CredentialRef}.
+ * @param value - candidate reference; a POSIX shell identifier such as `DEEPSEEK_API_KEY`.
+ * @returns the branded reference.
+ */
+export function credentialRef(value) {
+    if (!isCredentialRefName(value)) {
+        throw new TypeError(`credential ref "${value}" must match ${String(REF_PATTERN)}`);
+    }
+    return value;
+}
+/**
+ * Whether a raw string could name a reference at all. Consumers that receive
+ * environment-variable names from somewhere else — a provider library's own
+ * ambient discovery, a hook payload — ask this before resolving, because a name
+ * outside the grammar has no reference to miss and should read as "not set"
+ * rather than as a thrown error.
+ * @param value - candidate reference.
+ * @returns true when {@link credentialRef} would accept it.
+ */
+export function isCredentialRefName(value) {
+    return REF_PATTERN.test(value);
+}
+/**
+ * Whether a raw string could be a {@link credentialKey} segment at all.
+ * Consumers whose addressing units come from somewhere else — a settings dict
+ * key, a library's own provider id — ask this before building a key, because a
+ * unit outside the grammar can never have stored a record and should read as
+ * "nothing stored" rather than as a thrown error.
+ * @param value - candidate segment.
+ * @returns true when {@link credentialKey} would accept it as either segment.
+ */
+export function isCredentialKeySegment(value) {
+    return KEY_SEGMENT_PATTERN.test(value);
+}
+/**
+ * Brand a scope and an id as a {@link CredentialKey}.
+ * @param scope - the owning plugin's registered name, such as `llm-pi-ai`.
+ * @param id - that plugin's own addressing unit, such as a provider route key.
+ * @returns the branded key.
+ * @throws TypeError when either segment is not a lowercase hyphenated identifier.
+ */
+export function credentialKey(scope, id) {
+    for (const segment of [scope, id]) {
+        if (!KEY_SEGMENT_PATTERN.test(segment)) {
+            throw new TypeError(`credential key segment "${segment}" must match ${String(KEY_SEGMENT_PATTERN)}`);
+        }
+    }
+    return `${scope}/${id}`;
+}
+/**
+ * Brand a stored `<scope>/<id>` string as a {@link CredentialKey}. This is the
+ * read half of {@link credentialKey}, for a provider admitting keys off disk.
+ * @param value - candidate key in its joined form.
+ * @returns the branded key.
+ * @throws TypeError when the value is not exactly two valid segments.
+ */
+export function parseCredentialKey(value) {
+    const segments = value.split('/');
+    const [scope, id] = segments;
+    if (segments.length !== 2 || scope === undefined || id === undefined) {
+        throw new TypeError(`credential key "${value}" must be "<scope>/<id>"`);
+    }
+    return credentialKey(scope, id);
+}
+/**
+ * The owning plugin's name for one key. A record whose scope names no
+ * currently registered owner is an orphan, which a configuration surface must
+ * report as such rather than as a working credential.
+ * @param key - the key to read.
+ * @returns the scope segment.
+ */
+export function credentialKeyScope(key) {
+    // The brand's only constructors both validate two segments, so the split
+    // cannot come back short here.
+    return key.slice(0, key.indexOf('/'));
+}
+/**
+ * The owning plugin's own addressing unit for one key — the half that plugin
+ * chose, such as a provider route.
+ * @param key - the key to read.
+ * @returns the id segment.
+ */
+export function credentialKeyId(key) {
+    return key.slice(key.indexOf('/') + 1);
+}
+/**
+ * Abstract credential service over two key spaces that answer two questions.
+ *
+ * A {@link CredentialRef} answers "what is behind this environment-variable
+ * name", layered over the process environment, the provider-managed store, and
+ * `.env` files. One seam-wide rule binds that half: an empty stored value is
+ * absent everywhere — `resolve` skips it, `describe` reports it unconfigured —
+ * so a blank never masquerades as a configured secret.
+ *
+ * A {@link CredentialKey} answers "what credential does this plugin hold for
+ * this id". Nothing can layer here — an authorization grant has no
+ * environment to be read from — so presence of the record is the whole fact,
+ * and {@link modifyRecord} is the only write path because a correct write
+ * depends on the current value (a token refresh is read-decide-replace under
+ * one lock).
+ */
+export class CredentialProvider extends Service {
+    constructor(ctx) {
+        super(ctx, 'credentials');
+    }
+    /**
+     * Fan `credentials/reference-updated` out with contained listener failures: every
+     * listener runs, and a sync throw or async rejection is logged without
+     * changing the committed operation's outcome — except `INVARIANT`-coded
+     * failures, which rethrow after every listener ran (the rethrow reaches the
+     * caller only from synchronous listeners, so invariant checks on this event
+     * must not be async functions). Providers call this only after the write or
+     * reload actually committed, so a broken observer can never make a durable
+     * change look failed.
+     * @param ref - the reference whose stored value changed.
+     */
+    notifyUpdated(ref) {
+        this.fanOut('credentials/reference-updated', ref);
+    }
+    /**
+     * Fan `credentials/record-updated` out on exactly the terms
+     * {@link notifyUpdated} documents, for the record half of the seam.
+     * @param key - the record whose stored value changed.
+     */
+    notifyRecordUpdated(key) {
+        this.fanOut('credentials/record-updated', key);
+    }
+    /* jscpd:ignore-start -- deliberate symmetry with the settings seam's commit
+       fan-out: the contained-dispatch shape is the reviewed listener-lifecycle
+       contract, and extracting it would couple the two seams' event semantics. */
+    /** The contained dispatch both notifications run through; see {@link notifyUpdated}. */
+    fanOut(event, subject) {
+        let invariantFailure;
+        const args = [event, subject];
+        for (const listener of this.ctx.events.dispatch('emit', args)) {
+            try {
+                const returned = listener(subject);
+                if (returned != null && typeof returned.then === 'function') {
+                    void Promise.resolve(returned).then(undefined, (error) => {
+                        this.warnListenerFailure(event, subject, error);
+                    });
+                }
+            }
+            catch (error) {
+                if (error?.code === 'INVARIANT') {
+                    invariantFailure ??= error;
+                    continue;
+                }
+                this.warnListenerFailure(event, subject, error);
+            }
+        }
+        if (invariantFailure !== undefined)
+            throw invariantFailure;
+    }
+    /* jscpd:ignore-end */
+    /** Contained-listener diagnostic shared by the sync and async failure paths. */
+    warnListenerFailure(event, subject, error) {
+        this.ctx.logger.warn('credentials: a %s listener for "%s" failed', event, subject);
+        this.ctx.logger.warn(error);
+    }
+}
+export default CredentialProvider;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-credentials`.
+ * @module @hydraharness/harness-credentials/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "credentials-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,31 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-credentials`.
+ * @module @hydraharness/harness-credentials/invariant
+ */
+const PACKAGE_NAME = '@hydraharness/harness-credentials';
+/** Cordis companion plugin name. */
+export const name = 'credentials-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * Install the commit-event lifecycle contract: `credentials/reference-updated` names a
+ * committed provider-source change, so it can only fire while a credentials
+ * service is live — an emission after disposal means a provider leaked work
+ * past its teardown quiescence. The value relation itself (`describe`
+ * agreeing with `resolve`) is asynchronous provider I/O and stays pinned by
+ * each provider's own suite.
+ */
+const install = (ctx, fail) => {
+    ctx.on('credentials/reference-updated', (ref) => {
+        if (ctx.get('credentials') === undefined) {
+            fail(`credentials/reference-updated for "${ref}" emitted without a live credentials service`);
+        }
+    });
+};
+/**
+ * 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,82 @@
+/**
+ * Client-safe type surface of the credential seam: the two key brands, the
+ * stored-record union, and the seam's Cordis event declarations. Types only —
+ * no runtime code, and nothing here reaches a Host-only symbol, so a Client
+ * compilation face reads exactly the signature the Host emits.
+ *
+ * @module @hydraharness/harness-credentials/types
+ */
+import type { Branded } from '@hydraharness/harness-brand';
+/** Nominal reference to one credential: a POSIX-style environment-variable name. */
+export type CredentialRef = Branded<'CredentialRef'>;
+/**
+ * Nominal address of one stored credential record: `<scope>/<id>`, where
+ * `scope` is the registered name of the plugin that owns the record and `id`
+ * is that plugin's own addressing unit (an LLM adapter uses its provider route
+ * key).
+ *
+ * The scope is the owner rather than the domain because a record's payload is
+ * written in its owner's format: two plugins serving the same provider name
+ * would otherwise read each other's payload, and a record left behind by an
+ * uninstalled plugin could not be told apart from a live one. The `/` also
+ * keeps this grammar disjoint from {@link CredentialRef}, so the two key
+ * spaces can never collide.
+ */
+export type CredentialKey = Branded<'CredentialKey'>;
+/**
+ * A credential the harness itself understands: an api key, provider
+ * environment values, or both. Either field may be absent — a record carrying
+ * neither states that the owner confirmed this route authenticates from its
+ * own ambient discovery, which is a different fact from having no record.
+ */
+export interface ApiKeyRecord {
+    /** Discriminant. */
+    readonly kind: 'api-key';
+    /** The non-empty secret value, when this credential is a key at all. */
+    readonly key?: string;
+    /** Provider environment values such as `AWS_PROFILE`; names are POSIX identifiers. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * The product of one authorization grant, kept verbatim for its owner. The
+ * seam never reads, validates, or reshapes {@link payload}: it is written in
+ * the owning plugin's format and only that plugin can interpret it. The single
+ * constraint is that it survives a JSON round trip.
+ */
+export interface GrantRecord {
+    /** Discriminant. */
+    readonly kind: 'grant';
+    /** Owner-defined JSON value; opaque to the seam and to every other plugin. */
+    readonly payload: unknown;
+}
+/** One durable credential record, tagged by what the seam may do with it. */
+export type CredentialRecord = ApiKeyRecord | GrantRecord;
+declare module '@hydraharness/cordis' {
+    interface Events {
+        /**
+         * Committed change to a provider-managed credential source: a `set`, an
+         * `unset`, or an external edit observed in storage. Ambient
+         * process-environment changes are not observable and never emit. Listener
+         * failures are contained and logged — a sync throw and an async rejection
+         * alike — without changing the committed operation's outcome, except
+         * `INVARIANT`-coded failures, which rethrow after every listener ran;
+         * that rethrow reaches the emitter only from synchronous listeners, so
+         * invariant checks on this event must not be async functions.
+         * @param ref - the reference whose stored value changed.
+         * @mode emit
+         */
+        'credentials/reference-updated'(ref: CredentialRef): void;
+        /**
+         * Committed change to a stored credential record: a `modifyRecord` that
+         * wrote, a `deleteRecord` that removed, or an external edit observed in
+         * storage. Separate from `credentials/reference-updated` because the two key
+         * grammars are disjoint — a listener that received both on one event could
+         * not tell which space a subject belongs to. Listener failures are
+         * contained on the same terms as `credentials/reference-updated`.
+         * @param key - the record whose stored value changed.
+         * @mode emit
+         */
+        'credentials/record-updated'(key: CredentialKey): void;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,10 @@
+/**
+ * Client-safe type surface of the credential seam: the two key brands, the
+ * stored-record union, and the seam's Cordis event declarations. Types only —
+ * no runtime code, and nothing here reaches a Host-only symbol, so a Client
+ * compilation face reads exactly the signature the Host emits.
+ *
+ * @module @hydraharness/harness-credentials/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@hydraharness/harness-credentials",
+  "description": "Abstract credential seam (ctx.credentials): settings carry references to secrets, providers own the values",
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/credentials/credentials"
+  },
+  "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": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-brand": "^0.1.1-rc.5"
+  },
+  "devDependencies": {
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-brand": "^0.1.1-rc.5"
+  }
+}