feat(credential-sharing): implement the Credential Sharing OpenSpec (M1-M3)

New @logicsrc/plugin-credential-sharing: a provider-neutral secret-sync engine
with env/.env, Doppler, Railway, and GitHub Secrets adapters behind one
CredentialProvider contract.

- engine: inspect -> diff -> plan -> approve -> sync -> rollback -> audit/export
- dry-run is the default for sync; --approve writes; destructive changes gated
- fingerprint-based diffs (salted SHA-256); raw values never printed or stored in
  plans/runs/audit; rollback pre-image kept in a 0600 .logicsrc vault (gitignored)
- github-secrets is write-only for values (sealed-box via libsodium), so it cannot
  be a sync source or value-restoring rollback target
- CLI: real `logicsrc credentials <providers|inspect|diff|plan|approve|sync|
  rollback|audit|export>` (replaces the prior stub)
- 4 JSON schemas registered in @logicsrc/validators
- flip logicsrc.com/credential-sharing band from coming-soon to available
- 37 tests pass; full env->env lifecycle verified; artifacts schema-validate

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/cli/package.json

@@ -17,6 +17,7 @@
     "@logicsrc/account-core": "file:../account-core",
     "@logicsrc/plugin-core": "file:../plugin-core",
     "@logicsrc/plugin-coinpay": "file:../../plugins/coinpay",
+    "@logicsrc/plugin-credential-sharing": "file:../../plugins/credential-sharing",
     "@logicsrc/plugin-email-accounts": "file:../../plugins/email-accounts",
     "@logicsrc/plugin-feed-discovery": "file:../../plugins/feed-discovery",
     "@logicsrc/plugin-social-accounts": "file:../../plugins/social-accounts",

packages/cli/src/index.ts

@@ -2,6 +2,7 @@
 import { readFileSync } from "node:fs";
 import { evaluateAccountPolicy, scoreAccountActionRisk } from "@logicsrc/account-core";
 import { Command } from "commander";
+import { createCredentialEngine, listCredentialProviders, type CredentialEndpoint } from "@logicsrc/plugin-credential-sharing";
 import { listEmailAccountProviders } from "@logicsrc/plugin-email-accounts";
 import { discoverFeeds, listFeedProviders, probeSite, renderDiscoveryOutput, validateFeed, type FeedKind, type FeedOutputFormat } from "@logicsrc/plugin-feed-discovery";
 import { listSocialAccountProviders } from "@logicsrc/plugin-social-accounts";
@@ -375,33 +376,153 @@ program.command("plugins").option("--format <format>", "table, json, or markdown
   print(snapshot.plugins, options.format as OutputFormat);
 });
 
-const credentials = program.command("credentials").alias("creds").description("Credential-sharing OpenSpec commands.");
+const credentials = program.command("credentials").alias("creds").description("Credential Sharing OpenSpec: portable, auditable secret sync.");
 
-credentials.command("providers").option("--format <format>", "table, json, or markdown", "table").description("List credential sharing provider targets.").action((options) => {
-  print(
-    [
-      { id: "env", target: ".env files", mode: "read/write" },
-      { id: "doppler", target: "Doppler projects/configs", mode: "sync" },
-      { id: "railway", target: "Railway service variables", mode: "sync" },
-      { id: "github-secrets", target: "GitHub Actions and environment secrets", mode: "sync" }
-    ],
-    options.format as OutputFormat
-  );
-});
+function endpointFromOptions(options: Record<string, unknown>, prefix: "" | "from" | "to"): CredentialEndpoint {
+  const pick = (name: string) => {
+    const key = prefix ? `${prefix}${name[0].toUpperCase()}${name.slice(1)}` : name;
+    const value = options[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+  };
+  // The provider id is stored under the bare flag: options.from / options.to / options.provider.
+  const providerValue = options[prefix ? prefix : "provider"];
+  const provider = (typeof providerValue === "string" && providerValue.length > 0 ? providerValue : undefined) ?? (prefix === "to" ? "railway" : "env");
+  return { provider, path: pick("path"), project: pick("project"), config: pick("config"), service: pick("service"), scope: pick("scope") };
+}
 
-credentials.command("plan").option("--from <provider>", "Source provider", "env").option("--to <provider>", "Destination provider", "railway").option("--format <format>", "table, json, or markdown", "table").description("Describe a credential sync plan without moving secrets.").action((options) => {
-  print(
-    {
-      type: "logicsrc.credential_sync_plan",
-      from: options.from,
-      to: options.to,
-      policy: "redact-values",
-      approval: "required-before-write",
-      audit: "write target, key names, fingerprints, and timestamps; never write raw secret values"
-    },
-    options.format as OutputFormat
-  );
-});
+function withEndpointOptions(command: import("commander").Command, prefix: "" | "from" | "to", help: string) {
+  const flag = (name: string) => (prefix ? `--${prefix}-${name}` : `--${name}`);
+  return command
+    .option(`${flag("path")} <path>`, `${help} .env file path`)
+    .option(`${flag("project")} <id>`, `${help} project (Doppler project, Railway projectId, GitHub owner)`)
+    .option(`${flag("config")} <id>`, `${help} config (Doppler config, Railway environmentId, GitHub environment)`)
+    .option(`${flag("service")} <id>`, `${help} service (Railway serviceId, GitHub repo)`)
+    .option(`${flag("scope")} <scope>`, `${help} scope (GitHub: repo|org|environment)`);
+}
+
+function credentialEngine() {
+  return createCredentialEngine();
+}
+
+credentials
+  .command("providers")
+  .option("--format <format>", "table, json, or markdown", "table")
+  .description("List credential provider adapters and their capabilities.")
+  .action((options) => {
+    print(
+      listCredentialProviders().map((p) => ({
+        id: p.id,
+        name: p.name,
+        status: p.status,
+        reads_values: p.capabilities.readValues,
+        writes: p.capabilities.write,
+        auth: p.authRequirements.join(", ") || "none"
+      })),
+      options.format as OutputFormat
+    );
+  });
+
+withEndpointOptions(
+  credentials.command("inspect").requiredOption("--provider <provider>", "Provider id"),
+  "",
+  "Source"
+)
+  .option("--format <format>", "table, json, or markdown", "table")
+  .description("Inspect an endpoint: redacted key names and value fingerprints, never raw values.")
+  .action(async (options) => {
+    const snapshot = await credentialEngine().inspectCredentialSource(endpointFromOptions(options, ""));
+    print(options.format === "json" ? snapshot : snapshot.keys, options.format as OutputFormat);
+  });
+
+withEndpointOptions(
+  withEndpointOptions(
+    credentials.command("diff").requiredOption("--from <provider>", "Source provider").requiredOption("--to <provider>", "Destination provider"),
+    "from",
+    "Source"
+  ),
+  "to",
+  "Target"
+)
+  .option("--redact", "Explicitly redact values (always on; accepted for spec parity)")
+  .option("--format <format>", "table, json, or markdown", "table")
+  .description("Diff secrets between a source and target without moving anything.")
+  .action(async (options) => {
+    const diff = await credentialEngine().diffCredentialEndpoints(endpointFromOptions(options, "from"), endpointFromOptions(options, "to"));
+    print(options.format === "json" ? diff : diff.entries, options.format as OutputFormat);
+  });
+
+withEndpointOptions(
+  withEndpointOptions(
+    credentials.command("plan").requiredOption("--from <provider>", "Source provider").requiredOption("--to <provider>", "Destination provider"),
+    "from",
+    "Source"
+  ),
+  "to",
+  "Target"
+)
+  .option("--format <format>", "table, json, or markdown", "json")
+  .description("Build a redacted sync plan (stored for later approve/sync).")
+  .action(async (options) => {
+    const plan = await credentialEngine().createCredentialSyncPlan({
+      from: endpointFromOptions(options, "from"),
+      to: endpointFromOptions(options, "to")
+    });
+    print(plan, options.format as OutputFormat);
+  });
+
+credentials
+  .command("approve")
+  .requiredOption("--plan <id>", "Sync plan id")
+  .option("--keys <keys>", "Comma-separated keys to approve (default: all changes)")
+  .option("--format <format>", "table, json, or markdown", "json")
+  .description("Record an approval for a sync plan.")
+  .action((options) => {
+    const approval = credentialEngine().approveCredentialSync(options.plan, { keys: splitOption(options.keys) });
+    print(approval, options.format as OutputFormat);
+  });
+
+credentials
+  .command("sync")
+  .requiredOption("--plan <id>", "Sync plan id")
+  .option("--approve", "Approve and apply the plan (writes secrets)")
+  .option("--apply", "Apply the plan (alias for committing the write)")
+  .option("--format <format>", "table, json, or markdown", "json")
+  .description("Run a sync plan. Dry-run by default; --approve/--apply writes to the target.")
+  .action(async (options) => {
+    const engine = credentialEngine();
+    const apply = Boolean(options.approve || options.apply);
+    const approval = apply ? engine.approveCredentialSync(options.plan) : undefined;
+    const run = await engine.runCredentialSync(options.plan, { dryRun: !apply, approval });
+    print(run, options.format as OutputFormat);
+  });
+
+credentials
+  .command("rollback")
+  .requiredOption("--run <id>", "Sync run id to reverse")
+  .option("--format <format>", "table, json, or markdown", "json")
+  .description("Create a new sync plan that restores a run's captured pre-image.")
+  .action(async (options) => {
+    const plan = await credentialEngine().rollbackCredentialSync(options.run);
+    print(plan, options.format as OutputFormat);
+  });
+
+credentials
+  .command("audit")
+  .requiredOption("--run <id>", "Sync run id")
+  .option("--format <format>", "table, json, or markdown", "table")
+  .description("Export the audit trail for a run (key names, targets, fingerprints, timestamps).")
+  .action((options) => {
+    print(credentialEngine().exportCredentialAudit(options.run), options.format as OutputFormat);
+  });
+
+credentials
+  .command("export")
+  .requiredOption("--run <id>", "Sync run id")
+  .option("--format <format>", "table, json, or markdown", "json")
+  .description("Alias for audit: export a run's audit events.")
+  .action((options) => {
+    print(credentialEngine().exportCredentialAudit(options.run), options.format as OutputFormat);
+  });
 
 const accounts = program.command("accounts").description("Manage connected social and email accounts.");
 

packages/cli/src/registry.ts

@@ -1,10 +1,11 @@
 import { createPluginRegistry } from "@logicsrc/plugin-core";
 import { coinPayPlugin } from "@logicsrc/plugin-coinpay";
+import { credentialSharingPlugin } from "@logicsrc/plugin-credential-sharing";
 import { emailAccountsPlugin } from "@logicsrc/plugin-email-accounts";
 import { feedDiscoveryPlugin } from "@logicsrc/plugin-feed-discovery";
 import { socialAccountsPlugin } from "@logicsrc/plugin-social-accounts";
 import { uGigPlugin } from "@logicsrc/plugin-ugig";
 
 export function defaultPluginRegistry() {
-  return createPluginRegistry([coinPayPlugin, uGigPlugin, feedDiscoveryPlugin, socialAccountsPlugin, emailAccountsPlugin]);
+  return createPluginRegistry([coinPayPlugin, uGigPlugin, feedDiscoveryPlugin, socialAccountsPlugin, emailAccountsPlugin, credentialSharingPlugin]);
 }

packages/schemas/package.json

@@ -32,7 +32,11 @@
     "./agentad-ad-response": "./schemas/agentad-ad-response.schema.json",
     "./agentad-impression": "./schemas/agentad-impression.schema.json",
     "./agentad-click": "./schemas/agentad-click.schema.json",
-    "./agentad-campaign": "./schemas/agentad-campaign.schema.json"
+    "./agentad-campaign": "./schemas/agentad-campaign.schema.json",
+    "./credential-provider": "./schemas/logicsrc-credential-provider.schema.json",
+    "./credential-sync-plan": "./schemas/logicsrc-credential-sync-plan.schema.json",
+    "./credential-sync-run": "./schemas/logicsrc-credential-sync-run.schema.json",
+    "./credential-audit-event": "./schemas/logicsrc-credential-audit-event.schema.json"
   },
   "files": [
     "schemas"

packages/schemas/schemas/logicsrc-credential-audit-event.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/logicsrc-credential-audit-event.schema.json",
+  "title": "LogicSRC Credential Audit Event",
+  "type": "object",
+  "required": ["type", "id", "provider", "action", "key", "target", "principal", "decision", "dryRun", "createdAt"],
+  "additionalProperties": false,
+  "properties": {
+    "type": { "const": "logicsrc.credential_audit_event" },
+    "id": { "type": "string", "minLength": 1 },
+    "runId": { "type": "string", "minLength": 1 },
+    "planId": { "type": "string", "minLength": 1 },
+    "provider": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "action": { "type": "string", "pattern": "^[a-z][a-z0-9_-]*(:[a-z][a-z0-9_-]*)+$" },
+    "key": { "type": "string", "minLength": 1 },
+    "target": { "type": "string", "minLength": 1 },
+    "fingerprint": { "type": "string" },
+    "principal": {
+      "type": "object",
+      "required": ["type", "id"],
+      "additionalProperties": false,
+      "properties": {
+        "type": { "enum": ["user", "agent", "workflow", "plugin"] },
+        "id": { "type": "string", "minLength": 1 },
+        "trusted": { "type": "boolean" }
+      }
+    },
+    "decision": { "enum": ["allow", "approval_required", "deny"] },
+    "dryRun": { "type": "boolean" },
+    "createdAt": { "type": "string", "format": "date-time" }
+  }
+}

packages/schemas/schemas/logicsrc-credential-provider.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/logicsrc-credential-provider.schema.json",
+  "title": "LogicSRC Credential Provider",
+  "type": "object",
+  "required": ["id", "name", "description", "capabilities", "authRequirements", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "capabilities": {
+      "type": "object",
+      "required": ["readValues", "readNames", "write", "delete", "rollback", "audit"],
+      "additionalProperties": false,
+      "properties": {
+        "readValues": { "type": "boolean" },
+        "readNames": { "type": "boolean" },
+        "write": { "type": "boolean" },
+        "delete": { "type": "boolean" },
+        "rollback": { "type": "boolean" },
+        "audit": { "type": "boolean" }
+      }
+    },
+    "authRequirements": { "type": "array", "items": { "type": "string" } },
+    "status": { "enum": ["available", "planned"] }
+  }
+}

packages/schemas/schemas/logicsrc-credential-sync-plan.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/logicsrc-credential-sync-plan.schema.json",
+  "title": "LogicSRC Credential Sync Plan",
+  "type": "object",
+  "required": ["type", "id", "from", "to", "policy", "changes", "requiresApproval", "createdAt"],
+  "additionalProperties": false,
+  "$defs": {
+    "endpoint": {
+      "type": "object",
+      "required": ["provider"],
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "path": { "type": "string" },
+        "project": { "type": "string" },
+        "config": { "type": "string" },
+        "service": { "type": "string" },
+        "scope": { "type": "string" },
+        "metadata": { "type": "object" }
+      }
+    },
+    "change": {
+      "type": "object",
+      "required": ["key", "op", "destructive"],
+      "additionalProperties": false,
+      "properties": {
+        "key": { "type": "string", "minLength": 1 },
+        "op": { "enum": ["add", "update", "remove", "unchanged", "unknown"] },
+        "sourceFingerprint": { "type": "string" },
+        "targetFingerprint": { "type": "string" },
+        "destructive": { "type": "boolean" }
+      }
+    }
+  },
+  "properties": {
+    "type": { "const": "logicsrc.credential_sync_plan" },
+    "id": { "type": "string", "minLength": 1 },
+    "from": { "$ref": "#/$defs/endpoint" },
+    "to": { "$ref": "#/$defs/endpoint" },
+    "policy": {
+      "type": "object",
+      "required": ["redactValues", "requireApprovalForDestructive"],
+      "additionalProperties": false,
+      "properties": {
+        "redactValues": { "const": true },
+        "requireApprovalForDestructive": { "type": "boolean" },
+        "denyKeys": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "changes": { "type": "array", "items": { "$ref": "#/$defs/change" } },
+    "requiresApproval": { "type": "boolean" },
+    "rollbackOfRunId": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string", "format": "date-time" }
+  }
+}

packages/schemas/schemas/logicsrc-credential-sync-run.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.logicsrc.com/logicsrc-credential-sync-run.schema.json",
+  "title": "LogicSRC Credential Sync Run",
+  "type": "object",
+  "required": ["type", "id", "planId", "status", "dryRun", "results", "auditEventIds", "reversible", "startedAt", "finishedAt"],
+  "additionalProperties": false,
+  "properties": {
+    "type": { "const": "logicsrc.credential_sync_run" },
+    "id": { "type": "string", "minLength": 1 },
+    "planId": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["planned", "dry_run", "applied", "partial", "failed", "rolled_back"] },
+    "dryRun": { "type": "boolean" },
+    "results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["key", "op", "applied", "dryRun"],
+        "additionalProperties": false,
+        "properties": {
+          "key": { "type": "string", "minLength": 1 },
+          "op": { "enum": ["add", "update", "remove", "unchanged", "unknown"] },
+          "applied": { "type": "boolean" },
+          "dryRun": { "type": "boolean" },
+          "targetFingerprint": { "type": "string" },
+          "error": { "type": "string" }
+        }
+      }
+    },
+    "auditEventIds": { "type": "array", "items": { "type": "string" } },
+    "reversible": { "type": "boolean" },
+    "startedAt": { "type": "string", "format": "date-time" },
+    "finishedAt": { "type": "string", "format": "date-time" }
+  }
+}

packages/validators/src/schemas.ts

@@ -18,6 +18,10 @@ import agentadAdResponseSchema from "../../schemas/schemas/agentad-ad-response.s
 import agentadImpressionSchema from "../../schemas/schemas/agentad-impression.schema.json" with { type: "json" };
 import agentadClickSchema from "../../schemas/schemas/agentad-click.schema.json" with { type: "json" };
 import agentadCampaignSchema from "../../schemas/schemas/agentad-campaign.schema.json" with { type: "json" };
+import credentialProviderSchema from "../../schemas/schemas/logicsrc-credential-provider.schema.json" with { type: "json" };
+import credentialSyncPlanSchema from "../../schemas/schemas/logicsrc-credential-sync-plan.schema.json" with { type: "json" };
+import credentialSyncRunSchema from "../../schemas/schemas/logicsrc-credential-sync-run.schema.json" with { type: "json" };
+import credentialAuditEventSchema from "../../schemas/schemas/logicsrc-credential-audit-event.schema.json" with { type: "json" };
 
 export const schemas = {
   agent: agentSchema,
@@ -39,7 +43,11 @@ export const schemas = {
   "agentad-ad-response": agentadAdResponseSchema,
   "agentad-impression": agentadImpressionSchema,
   "agentad-click": agentadClickSchema,
-  "agentad-campaign": agentadCampaignSchema
+  "agentad-campaign": agentadCampaignSchema,
+  "credential-provider": credentialProviderSchema,
+  "credential-sync-plan": credentialSyncPlanSchema,
+  "credential-sync-run": credentialSyncRunSchema,
+  "credential-audit-event": credentialAuditEventSchema
 } as const;
 
 export type SchemaKind = keyof typeof schemas;