Auth refs for portable bundles and multi-environment workflows

[chubes4]

Problem

Bundles cannot ship raw credentials, but they need to declare credential requirements for handlers and sources.

Desired shape

Use symbolic auth refs that can be exported, imported, resolved locally, and reported when missing.

Example refs:

• github:automattic
• mgs:a8c
• slack:a8c
• wpcom:primary

Needed behavior:

• export rewrite: concrete auth config to symbolic ref
• import resolve: symbolic ref to local credential/config
• unresolved auth warnings
• per-flow/per-handler auth dependency report
• no secrets in bundle files, diffs, or PendingActions

Acceptance criteria

• Bundle manifests can declare auth refs.
• Handler configs can refer to auth refs instead of raw secret material.
• Import/upgrade reports unresolved refs without failing unrelated artifacts.
• Auth providers can participate in ref resolution.
• Secret values are never emitted in bundle output or preview diffs.

Context

This is required before sharing a WooCommerce brain bundle that uses GitHub, MGS, Slack, or WP.com sources.

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Drafting the issue from product/design discussion; Chris remains responsible for prioritization and implementation.

[chubes4]

Partially shipped in Data Machine v0.97.1. PR #1549 added AuthRef, AuthRefResolver, AuthRefResolverInterface, the datamachine_auth_ref_resolvers / datamachine_resolve_auth_ref seams, secret-stripping, unresolved-ref warning envelopes, and BundleSchema reservations for auth-refs. What remains: bundle export/import does not yet rewrite concrete handler auth config to auth_ref values or resolve auth_ref values back into local handler config during install/upgrade. Per-flow/per-handler auth dependency reports are also still an integration slice. Leaving open for the end-to-end bundle auth-ref workflow.

[chubes4]

Update after Data Machine v0.98.0: PR #1557 shipped the handler-config auth_ref foundation. It added AuthRefHandlerConfig, default datamachine_handler_config_to_auth_ref / datamachine_auth_ref_to_handler_config filter callbacks, BaseAuthProvider conversion/resolution hooks, first-party email_imap:default mapping, and runtime auth_ref resolution in fetch/publish/upsert execution paths with secret-safe errors. This is a major step beyond the value-object contract from #1549. Still remaining before this issue is fully complete: AgentBundler export does not yet rewrite every bundle handler_config through the auth_ref export filter, import/upgrade planning does not yet produce a per-flow/per-handler unresolved-auth dependency report, and provider mappings beyond the representative email provider still need to be added by their auth providers. Leaving open for that end-to-end portable bundle auth workflow.