@harperfast/harper 5.2.0-alpha.5 → 5.2.0-alpha.6

package/dist/components/componentSecrets.d.ts

@@ -1,5 +1,17 @@
-/** A per-component secrets view: read-only name→value map exposed as `import { secrets } from 'harper'`. */
-export type SecretsView = Readonly<Record<string, string>>;
+/**
+ * Subscribe to a secret's current value and any subsequent changes (#1776). Yields the current value
+ * first, then on each change; `undefined` means the component has no access right now (never granted,
+ * revoked, or deleted) — the same thing `secrets[name]` reads as. The stream stays open across that,
+ * so a re-grant/re-add resumes on the same iterator.
+ */
+export type SecretSubscribe = (name: string) => AsyncIterableIterator<string | undefined>;
+/**
+ * A per-component secrets view: read-only name→value map exposed as `import { secrets } from 'harper'`,
+ * plus the reserved, non-enumerable `subscribe(name)` method for live change subscription.
+ */
+export type SecretsView = Readonly<Record<string, string>> & {
+    readonly subscribe: SecretSubscribe;
+};
 export type UnsatisfiedReason = 'missing' | 'ungranted' | 'custody-unavailable';
 /** A declared-but-unsatisfied env expectation — metadata only, never values. */
 export interface UnsatisfiedDeclaration {
@@ -39,12 +51,26 @@ export declare function materializeGlobalSecrets(): Promise<void>;
 export declare function processComponentEnv(componentName: string, envConfig: unknown): void;
 /** Declared-but-unsatisfied env expectations for a component — metadata only, for status surfaces. */
 export declare function getUnsatisfiedEnv(componentName: string): UnsatisfiedDeclaration[];
+/** Close every live subscription owned by a component (component reload/unload). */
+export declare function closeComponentSubscriptions(componentName: string): void;
+/** A Scope of this identity is now open — hold its live secret subscriptions until it releases. */
+export declare function retainComponentSubscriptions(componentName: string): void;
+/** A Scope of this identity closed — end the identity's subscriptions once the last holder is gone. */
+export declare function releaseComponentSubscriptions(componentName: string): void;
 /**
- * The secrets view for a component: scoped-tier rows granted to it, plus its DECLARED names
- * resolved from process.env (global-tier materialized values, env literals, or real env vars).
- * The superset lets app code use `secrets.FOO` uniformly, and lets ops later tighten a secret from
- * global to granted without breaking the app. Values are decrypted eagerly at load; the object is
- * frozen and enumerable (`Object.keys`, spread).
+ * The secrets view for a component: scoped-tier rows granted to it, plus its DECLARED names resolved
+ * from process.env (global-tier materialized values, env literals, or real env vars). The superset
+ * lets app code use `secrets.FOO` uniformly, and lets ops later tighten a secret from global to
+ * granted without breaking the app.
+ *
+ * It is a LIVE view (#1776): a Proxy that resolves each read from the current snapshot, so a scoped
+ * secret's rotation/revoke is reflected by a fresh `secrets.FOO` read under every loader — including a
+ * view captured once by the vm/compartment loader or held as `const v = scope.secrets` (only a
+ * value destructured out, `const { FOO } = secrets`, is a point-in-time copy). Declared global names
+ * still resolve from `process.env` (reload-only). Read-only and null-prototype, so Object.prototype
+ * members can't masquerade as secrets and the view can't be mutated. `subscribe` is a reserved,
+ * non-enumerable method (skipped by Object.keys/spread); a secret literally named `subscribe` is
+ * shadowed by it — logged once when observed.
  */
 export declare function getSecretsForComponent(componentName: string): SecretsView;
 /** Run `fn` with `secrets` bound to the named component (no-op when name is undefined). */