01 — IdP recovery codes in AWS Secrets Manager

STATUS: STUB. This chapter documents the intended design. The IAM role, MFA policy, and per-secret CloudTrail audit have NOT yet been provisioned. The naming convention is locked.

PRODUCTION GATE. Per the canonical CLAUDE.md hard rules: no --env prd deploy of any Worker, Pages site, or infrastructure module proceeds until the implementation in §6 below is complete and verified. Dev and stg deploys may proceed against the stub.

This chapter specifies how Adventive stores the recovery material that lets the security owner rebuild the Cloudflare Zero Trust IdP chain after a JumpCloud, Google Workspace, or Duo incident. The canonical store is AWS Secrets Manager (not Cloudflare Secrets Store — see the parent README for why).

1. What lives here

Three classes of secret, all related to the IdP integrations that gate Adventive Tools Auth (tools.adventive.io and friends):

Secret	Source-of-truth	Adventive Secrets Manager name
JumpCloud SAML application metadata XML	JumpCloud admin console — Adventive Cloudflare Access SAML app	adventive-idp-recovery-jumpcloud-saml-metadata
Google Workspace OIDC client ID + secret	Google Workspace admin — Adventive Cloudflare Access OIDC app	adventive-idp-recovery-google-oidc-credentials
Duo integration key + secret key + API hostname	Duo admin — Cloudflare Zero Trust application	adventive-idp-recovery-duo-integration

Future additions go here too — for example, a Cloudflare account-level API recovery token (adventive-cloudflare-account-api-recovery) if and when one is provisioned.

2. Naming convention

adventive-idp-recovery-<idp>-<artifact>. Lowercase, hyphen-separated. The adventive-idp-recovery- prefix is the namespace marker — it makes the set greppable for the audit policy and clearly distinguishes recovery material from runtime secrets.

Do not use AWS Secrets Manager versioning to store rotated recovery codes. Each rotation REPLACES the secret value in place; the prior value is invalidated upstream (in JumpCloud / Google / Duo) at the same time.

3. IAM role — AdventiveIdPRecoveryReader

A single dedicated IAM role grants human access to the recovery material. The role’s permissions are narrow and MFA-gated.

3.1 Trust policy

Allow assumption by named IAM users (the two-or-more Adventive engineers approved to access recovery material). No long-lived service-account access.

3.2 Permissions policy (intended shape)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadIdPRecoverySecrets",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:*:*:secret:adventive-idp-recovery-*",
      "Condition": {
        "Bool": { "aws:MultiFactorAuthPresent": "true" },
        "NumericLessThan": { "aws:MultiFactorAuthAge": "900" }
      }
    },
    {
      "Sid": "DecryptWithRecoveryCMK",
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "<arn-of-adventive-idp-recovery-cmk>",
      "Condition": {
        "Bool": { "aws:MultiFactorAuthPresent": "true" }
      }
    }
  ]
}

The 15-minute MFA freshness condition (aws:MultiFactorAuthAge < 900) prevents long-lived session tokens from being used to silently read recovery codes hours after the operator logged in.

3.3 Membership

At least two Adventive engineers. Ideally the membership overlaps with — but is not identical to — the Cloudflare Secrets Store admin set. Membership changes go through a documented procedure (Phase 1 follow-up of this chapter).

4. Encryption — dedicated KMS CMK

A dedicated customer-managed KMS key (adventive-idp-recovery-cmk) encrypts the secrets, distinct from the default AWS-managed key. This:

• Lets the recovery-CMK key policy independently constrain who can decrypt.
• Surfaces decryption attempts in CloudTrail as a separate event class.
• Allows revocation of decrypt access without rotating every secret.

The CMK is provisioned in the same AWS region as the Secrets Manager secrets. Region choice TBD — likely us-east-1 to match the existing Adventive infrastructure footprint.

5. Audit — CloudTrail

CloudTrail logs every GetSecretValue, DescribeSecret, and Decrypt call against the recovery namespace with caller identity, source IP, and MFA status. A CloudTrail event-selector rule scoped to the adventive-idp-recovery-* ARN pattern routes these events to:

• A monitored log destination (TBD — New Relic Logs is the standard Adventive log sink; if that ships before this chapter is implemented, send recovery audit events there too).
• A Slack notification (channel TBD) for every successful read, so a recovery use is visible in real time.

6. Production-gate implementation checklist

These are the items that MUST be done and confirmed before any --env prd deploy can proceed. Dev and stg are exempt — they may deploy against the stub.

• CMK provisioned. adventive-idp-recovery-cmk exists in the target AWS region with a documented key policy and at least one administrative member outside the day-to-day platform team.
• IAM role provisioned. AdventiveIdPRecoveryReader exists with the permissions policy in §3.2, MFA conditions in place, and 15-minute MFA freshness configured.
• At least two role members. Two Adventive engineers with MFA-enabled IAM users approved to assume the role.
• Three IdP recovery secrets seeded. adventive-idp-recovery-jumpcloud-saml-metadata, adventive-idp-recovery-google-oidc-credentials, adventive-idp-recovery-duo-integration exist in AWS Secrets Manager with current cleartext values pasted from the IdP admin consoles, scope-tagged as idp-recovery.
• CloudTrail event selector configured. The adventive-idp-recovery-* ARN pattern is captured in CloudTrail with the destination wired to the agreed log sink + Slack channel.
• One recovery rehearsal completed. A designated role member assumes the role with MFA and successfully retrieves one secret. The CloudTrail event is verified. The rehearsal is documented in the Tools Auth runbook.
• Runbook updated. docs/projects/adventive-tools-auth/04-runbook.md “IdP rotation” section points at the role and the seeded secret names; the prior “1Password” reference is removed (this is part of the docs sweep that establishes this chapter, not a separate task).

When every item is checked and verified, this chapter’s status changes from STUB to ACTIVE and the production-gate hard rule in canonical CLAUDE.md no longer blocks prd deploys.

7. Until the gate is met

While this is a stub, the practical impact on every Adventive engineering project:

• Dev and stg deploys: proceed normally. The stub is not enforced at the deploy level for non-prd environments.
• Prd deploys: forbidden by canonical CLAUDE.md hard rule. Any attempt should be paused and the implementer should pick up §6 above.
• Runbook: the Adventive Tools Auth runbook (docs/projects/adventive-tools-auth/04-runbook.md) points readers here for IdP recovery — they will see the STUB banner and the gate language. Do not paper over.

8. Cross-references

• Canonical CLAUDE.md §3 hard rules — establishes the prd gate.
• docs/platform/cloudflare/workers/06-observability-opentelemetry.md — companion pattern for Cloudflare Worker runtime secrets (different store, different purpose).
• docs/projects/adventive-tools-auth/04-runbook.md — Adventive Tools Auth runbook, IdP rotation procedures.
• docs/projects/adventive-tools-auth/decisions/2026-05-04-jumpcloud-primary-google-fallback.md — locks in the IdP set this chapter is recovery material for.
• docs/projects/adventive-tools-auth/decisions/2026-05-04-duo-as-cloudflare-mfa.md — locks in Duo as the MFA provider whose integration key is part of the recovery set.