qring-mcp

Instructions

Implementation Reference

• src/core/keyring.ts:155-242 (handler)

  Implementation of the setSecret handler which stores a secret with quantum metadata and handles propagation to entangled secrets.

  export function setSecret(
    key: string,
    value: string,
    opts: SetSecretOptions = {},
  ): void {
    const scope = opts.scope ?? "global";
    const scopes = resolveScope({ ...opts, scope });
    const { service } = scopes[0];
    const source = opts.source ?? "cli";
  
    // Check if there's an existing envelope to preserve metadata
    const existing = readEnvelope(service, key);
  
    let envelope: QuantumEnvelope;
  
    const rotFmt = opts.rotationFormat ?? existing?.meta.rotationFormat;
    const rotPfx = opts.rotationPrefix ?? existing?.meta.rotationPrefix;
    const prov = opts.provider ?? existing?.meta.provider;
  
    if (opts.states) {
      envelope = createEnvelope("", {
        states: opts.states,
        defaultEnv: opts.defaultEnv,
        description: opts.description,
        tags: opts.tags,
        ttlSeconds: opts.ttlSeconds,
        expiresAt: opts.expiresAt,
        entangled: existing?.meta.entangled,
        rotationFormat: rotFmt,
        rotationPrefix: rotPfx,
        provider: prov,
      });
    } else {
      envelope = createEnvelope(value, {
        description: opts.description,
        tags: opts.tags,
        ttlSeconds: opts.ttlSeconds,
        expiresAt: opts.expiresAt,
        entangled: existing?.meta.entangled,
        rotationFormat: rotFmt,
        rotationPrefix: rotPfx,
        provider: prov,
      });
    }
  
    // Preserve access count from existing
    if (existing) {
      envelope.meta.createdAt = existing.meta.createdAt;
      envelope.meta.accessCount = existing.meta.accessCount;
    }
  
    writeEnvelope(service, key, envelope);
    logAudit({ action: "write", key, scope, source });
  
    // Propagate to entangled secrets
    const entangled = findEntangled({ service, key });
    for (const target of entangled) {
      try {
        const targetEnvelope = readEnvelope(target.service, target.key);
        if (targetEnvelope) {
          if (opts.states) {
            targetEnvelope.states = opts.states;
          } else {
            targetEnvelope.value = value;
          }
          targetEnvelope.meta.updatedAt = new Date().toISOString();
          writeEnvelope(target.service, target.key, targetEnvelope);
          logAudit({
            action: "entangle",
            key: target.key,
            scope: "global",
            source,
            detail: `propagated from ${key}`,
          });
        }
      } catch {
        // entangled target may not exist
      }
    }
  
    fireHooks({
      action: "write",
      key,
      scope,
      timestamp: new Date().toISOString(),
      source,
    }, envelope.meta.tags).catch(() => {});
  }

• src/core/keyring.ts:45-64 (schema)

  Schema/interface definition for the options allowed when calling setSecret.

  export interface SetSecretOptions extends KeyringOptions {
    /** Environment states for superposition */
    states?: Record<Environment, string>;
    /** Default environment */
    defaultEnv?: Environment;
    /** TTL in seconds (quantum decay) */
    ttlSeconds?: number;
    /** Expiry timestamp */
    expiresAt?: string;
    /** Description */
    description?: string;
    /** Tags */
    tags?: string[];
    /** Format for auto-rotation (e.g. "api-key", "password", "uuid") */
    rotationFormat?: string;
    /** Prefix for auto-rotation (e.g. "sk-") */
    rotationPrefix?: string;
    /** Provider for liveness validation (e.g. "openai", "stripe") */
    provider?: string;
  }