CRM Sync — Key Management Lifecycle

Version: 1.5 Date: 2026-07-03 (v1.4: 2026-06-22; v1.2: 2026-06-15; v1.1: 2026-06-11; v1.0: 2026-05-26) Scope: Dev → Stage → Prod key management, consulting team workflow, stakeholder publish, per-market site tokens, Interactive Key Ceremony (agent-safe credential operations), .env/CLI-as-AI-exposure-surface threat model, organizational RACI + tech→business ownership, regulated-industry glossary, GraphQL/server-side migration significance, self-service tenant key management (app owners, §13), server-side session revocation Companion: KEY-CEREMONY-LOOP-REVIEW.md — recurring, non-custodial automation checklist that continuously attests this lifecycle (the QA/Compliance verify lane as a /loop).

0. Executive Summary (Challenge → Solution)

Each pillar of this lifecycle stated as one plain challenge/solution sentence, with the supporting detail bulleted beneath. Section references point to the full treatment.

Agent-safe key ceremony (§9). Challenge: an AI/automation agent is a superb operator but a liability as a secret-holder — once it can mint or read a key, that secret's reach includes its context window, the transcript, and every log it touches. Solution: run every privileged credential op as a two-role ceremony where a human executes and the agent only prepares, verifies, and records.

• A permission classifier blocks the agent from running credential-minting commands.
• Secrets are injected by reference ($(cat ~/.crm-*-key)) — never inline, printed, or committed.
• Read-back is masked (564bbe…9298) or a (set) flag — the value never returns.
• Rotation is additive-only (root key never replaced), so a botched ceremony can't lock anyone out.
• Every ceremony files a fingerprint-only audit record (sha256[:8]), safe to publish.

.env + CLI as an AI exposure surface (§9.6). Challenge: the everyday way to manage secrets — a .env file plus wrangler/curl at the terminal — is exactly what leaks to an agent sharing the machine. Solution: treat .env and the CLI as hostile-to-AI by default and route every secret around the agent.

• Privileged secrets live in write-only Cloudflare secrets / KV, never a checked-out .env.
• The human runs the interactive command; the agent is blocked and hands it over.
• Verification is by side-effect (a 200, an old key now 401), never by echoing the value.
• Rotation happens in the config layer (KV beats env) — no .env edit, no redeploy.

Organizational roles & RACI (§9.7, §12). Challenge: a bare two-person ceremony doesn't say who does what once a real org is involved. Solution: map functional roles onto the ceremony with a RACI matrix that has exactly one Accountable per activity.

• Deployment Officer executes the write (= the Security Human).
• PMO schedules; QA/Release Manager verifies stage→prod; Compliance Officer attests cadence.
• DPO approves anything touching the PII plane — but is Consulted, never Accountable.
• The Agent never appears as Responsible or Accountable for a privileged write.

Formal definitions for regulated industry (§10). Challenge: auditors won't accept colloquial terms — controls must map to named standards. Solution: a glossary giving each term its normative definition and citation.

• Dual control & split knowledge → PCI-DSS; SoD & least privilege → NIST SP 800-53.
• Crypto Officer → FIPS 140-3; cryptoperiod & key rotation → NIST SP 800-57.
• DPO & security of processing → GDPR Art. 37–39 / Art. 32.
• Our "blast radius" is formalized as scope of compromise; "fingerprint" as a truncated key hash.

GraphQL / server-side migration significance (§11). Challenge: Shopify→GraphQL and Google→GA4-server-side concentrate credential power into fewer, high-privilege, server-resident secrets — just as AI agents do more of the integration work. Solution: make least-privilege scoping + rotation + the ceremony load-bearing controls at the worker boundary.

• One GraphQL endpoint = one token = a whole-schema scope of compromise.
• GA4 server-side measurement introduces a real api_secret where client-side had none.
• Platform-native token expiry/rotation now aligns with the §8.1 cadence.
• Agents that codegen GraphQL must stay non-custodial (§9.1).

Ownership, tech → business (§12). Challenge: without a single owner, accountability diffuses and the control silently rots. Solution: name one Accountable per activity, escalating from execution on the technical floor to business risk ownership.

• Deployment Officer / Engineering Lead carry technical Responsibility.
• CISO (or Head of Security / VP Eng) is Accountable for residual risk — a business function.
• DPO is Consulted; the Agent is never A or R for a write.
• Two lines must never collapse: executor ≠ attester, and Accountable ≠ the doer.

Self-service tenant key management (§13). Challenge: every key reset routed through the platform operator makes the operator a bottleneck — and a custodian — for credentials that rightfully belong to each app owner. Solution: the purchased product includes the key system: owners run their own lifecycle through an entitlement-gated wizard; the platform demonstrates it but never holds the key.

• One dedicated key per store; ownership proven by purchase-granted entitlement, never self-assigned.
• Rotation is mint-before-revoke — a mid-flight failure can never leave the owner keyless.
• The key is returned exactly once at mint; list views show fingerprints only.
• Every rotate/revoke lands in a per-store, fingerprint-only append-only audit ledger.
• Login sessions are revoked server-side on logout (denylist), so a cached session cannot outlive its logout.

1. Environments

2. Key Types

3. Dev Environment

Who: Engineering team (Persona A)

# Start local dev
cd workers/crm-sync
wrangler dev --config wrangler.toml

Key rules:

• Use .dev.vars file for local secrets (never committed)
• Generate throwaway keys: openssl rand -hex 16
• No real Shopify/Google/Xano credentials — use test accounts
• KV is local (miniflare) — tenant tokens and rotatable keys are ephemeral

.dev.vars example:

ADMIN_KEY=dev-only-throwaway-key-1234567890
JWT_SECRET=dev-jwt-secret-not-for-production
XANO_API_KEY=xano-dev-key
GOOGLE_CLIENT_SECRET=google-dev-secret
RESEND_API_KEY=re_test_xxxxx

Extension dev:

cd extensions/crm-auth
npm run dev    # webflow extension serve 1338 + tsc --watch

4. Stage Environment

Who: Engineering + consulting team Worker: cf-worker-crm-sync on crm.story-story.ai Store: hx-stage.myshopify.com

4.1 Initial Stage Setup

# Set stage secrets (one-time)
cd workers/crm-sync
openssl rand -hex 24 | wrangler secret put ADMIN_KEY --config wrangler.toml
openssl rand -hex 24 | wrangler secret put JWT_SECRET --config wrangler.toml
wrangler secret put GOOGLE_CLIENT_SECRET --config wrangler.toml   # from Google Console
wrangler secret put XANO_API_KEY --config wrangler.toml           # from Xano stage workspace
wrangler secret put RESEND_API_KEY --config wrangler.toml         # from Resend (test mode)

4.2 Stage Key Inventory

4.3 Consulting Team Stage Access

# Engineering lead creates rotatable key for consulting team
curl -X POST https://crm.story-story.ai/admin/rotate-key \
  -H "Authorization: Bearer $ROOT_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"consulting-stage-key-minimum-20chars"}'

# Consulting team uses this key for all stage admin operations
# They CANNOT access root key or CLI — only API-level operations

Consulting team can:

• Access /setup, /settings, /onboarding with their key
• Provision tenant tokens for demo clients
• Read/write config for any shop on the stage worker
• Rotate their own key if compromised

Consulting team cannot:

• Access Cloudflare dashboard or CLI
• Change root ADMIN_KEY
• Modify worker code or deploy
• Access other Cloudflare secrets (JWT_SECRET, etc.)

Verified in practice (2026-06-11): the full delegation lifecycle — root-authenticated create, masked status check (GET /admin/rotate-key returns a key_preview only, never the key), delegate authentication on admin endpoints, self-rotation, and root-only revocation (DELETE /admin/rotate-key) — is exercised and confirmed on stage. Rotating or revoking the delegate key never invalidates the root key or tenant tokens.

4.4 Market Site Tokens (multi-site localization)

Each localized market (e.g. a per-country Webflow site clone) authenticates with its own site-scoped token, because Webflow site tokens cannot cross sites:

# Store a market's site token (write-only field; created in that site's
# Webflow settings → Apps & Integrations → API access)
curl -X POST https://crm.story-story.ai/admin/markets \
  -H "Authorization: Bearer $ADMIN_OR_DELEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"region":"ca","cms_token":"<site token>"}'

Security properties:

• Write-only: no endpoint ever returns the token. Reads show a "(set)" flag only.
• Stored apart from config: KV market_cms_token:{region}, never inside the market config object that GET /admin/markets returns.
• Scoped blast radius: a leaked market token exposes exactly one site — not the primary site, not the worker, not other markets.
• Content gating: public localized-export endpoints serve only reviewed/published translation overrides; machine-translation drafts cannot leak through any public surface.

5. Prod Environment

Who: Depends on stakeholder tier

5.1 Persona A (App Creator) — Prod Deploy

# Create production worker (separate from stage)
cd workers/crm-sync
cp wrangler.toml wrangler.prod.toml
# Edit wrangler.prod.toml: name = "cf-worker-crm-sync-prod", new KV namespace ID

# Set production secrets
openssl rand -hex 32 | wrangler secret put ADMIN_KEY --config wrangler.prod.toml
openssl rand -hex 32 | wrangler secret put JWT_SECRET --config wrangler.prod.toml
wrangler secret put GOOGLE_CLIENT_SECRET --config wrangler.prod.toml
wrangler secret put XANO_API_KEY --config wrangler.prod.toml
wrangler secret put RESEND_API_KEY --config wrangler.prod.toml

# Deploy
wrangler deploy --config wrangler.prod.toml

# Set up custom domain
# (via Cloudflare Workers Custom Domains API or dashboard)

5.2 Persona B (Shared) — Prod Onboarding

# A provisions tenant token for B's store
curl -X POST https://crm.{prod-domain}/admin/provision-token \
  -H "Authorization: Bearer $PROD_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shop": "client-store.myshopify.com",
    "label": "client-name",
    "scopes": ["config:read", "config:write"]
  }'
# → Returns: crm_t_xxxx

# B receives ONLY:
#   1. Tenant token (crm_t_xxxx)
#   2. Worker URL (https://crm.{prod-domain})
#   3. Extension auto-fills the URL
# B never sees: root key, Cloudflare secrets, KV internals

5.3 Persona C (Private Worker) — Prod Handoff

# C deploys their own worker from the source code license
cd workers/crm-sync
wrangler deploy --config wrangler.toml   # their own Cloudflare account

# C sets their own root key
openssl rand -hex 32 | wrangler secret put ADMIN_KEY --config wrangler.toml

# C creates a rotatable key for day-to-day operations
curl -X POST https://their-worker.their-domain.com/admin/rotate-key \
  -H "Authorization: Bearer $THEIR_ROOT_KEY" \
  -H "Content-Type: application/json" -d '{}'
# → Returns auto-generated rotatable key

# C provisions tenant tokens for each of their Shopify stores
curl -X POST https://their-worker.their-domain.com/admin/provision-token \
  -H "Authorization: Bearer $ROTATABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shop":"store-1.myshopify.com","label":"store-1"}'

curl -X POST https://their-worker.their-domain.com/admin/provision-token \
  -H "Authorization: Bearer $ROTATABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shop":"store-2.myshopify.com","label":"store-2"}'

6. Consulting Team → Live Deploy Workflow

6.1 Pre-Deploy Checklist

6.2 Key Handoff Matrix

                    ┌─────────────────────────────────────────────┐
                    │           ENGINEERING (A)                    │
                    │  Root ADMIN_KEY (prod)                       │
                    │  All Cloudflare secrets                      │
                    │  Google Console, Xano, Resend accounts       │
                    └────────────┬────────────────────────────────┘
                                 │
                    Creates rotatable key
                                 │
                    ┌────────────▼────────────────────────────────┐
                    │        CONSULTING TEAM                       │
                    │  Rotatable admin key (prod)                  │
                    │  Can: provision tokens, manage config,       │
                    │       access setup/settings, rotate own key  │
                    │  Cannot: deploy, change secrets, root access │
                    └────────────┬────────────────────────────────┘
                                 │
                    Provisions tenant token
                                 │
              ┌──────────────────┼──────────────────┐
              │                                      │
   ┌──────────▼──────────┐              ┌────────────▼───────────┐
   │    CLIENT (B)        │              │    CLIENT (C)           │
   │  Tenant token only   │              │  Full source + own key  │
   │  crm_t_xxxx          │              │  Root + rotatable       │
   │  Extension auto-fill │              │  Own infra, own deploy  │
   │  No admin access     │              │  Multi-tenant capable   │
   └──────────────────────┘              └────────────────────────┘

6.3 Post-Launch Key Rotation

After consulting team completes handoff:

# Option 1: Rotate consulting key (new key, team retains support access)
curl -X POST https://crm.{prod-domain}/admin/rotate-key \
  -H "Authorization: Bearer $CONSULTING_KEY" \
  -H "Content-Type: application/json" -d '{}'
# Old consulting key instantly invalid, new key for ongoing support

# Option 2: Revoke consulting key entirely (root-only)
curl -X DELETE https://crm.{prod-domain}/admin/rotate-key \
  -H "Authorization: Bearer $ROOT_ADMIN_KEY"
# Only root key valid — consulting team fully cut off

# Option 3: Issue new consulting key with different holder
curl -X POST https://crm.{prod-domain}/admin/rotate-key \
  -H "Authorization: Bearer $ROOT_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"new-support-team-key-at-least-20"}'

7. Stakeholder Publish — Key Inventory

7.1 What Each Stakeholder Receives at Publish

7.2 Publish Ceremony (Per Stakeholder)

Stakeholder B publish:

1. A provisions crm_t_* token scoped to B's shop
2. A sends B: tenant token + worker URL
3. B installs Webflow extension → auto-fills worker URL
4. B enters tenant token in Config tab
5. B installs Shopify app (OAuth flow auto-provisions admin token)
6. B connects Google login via extension Auth tab
7. Done — B operates entirely through extension UI

Stakeholder C publish:

1. A delivers licensed source code repo
2. C deploys to their Cloudflare account (wrangler deploy)
3. C sets root ADMIN_KEY via CLI
4. C creates rotatable key via API (for team operations)
5. C sets up their own: Google project, Xano workspace, Resend account
6. C registers their Shopify app in Partners
7. C updates Webflow extension URL to their worker domain
8. C provisions tenant tokens per Shopify store
9. C sets plan: "private" in config
10. Done — C is fully independent, A has no access

8. Security Policies

8.1 Key Rotation Schedule

8.2 Incident Response — Key Compromise

8.3 Environment Isolation Rules

• Never use prod keys in stage or dev
• Never share root keys via email, Slack, or any unencrypted channel
• Never commit secrets to git (use .dev.vars locally, wrangler secret put remotely)
• Stage and prod use separate KV namespaces — no cross-contamination
• Consulting team gets rotatable key only — never root, never CLI access

9. Interactive Key Ceremony (Agent-Safe Credential Operations)

Primary feature. Every privileged credential operation in this stack — mint, rotate, revoke, set — runs as a two-role ceremony: a named Security Human executes the privileged command; an Agent (AI/automation, e.g. Claude Code) prepares, verifies, and records but never mints, holds, or transports a secret. This is the normative procedure behind FUNCTIONAL-SPEC.md §13 FR-HANDOFF-02.

9.0 Heritage — an established discipline, applied to a new threat

"Key ceremony" is not a term invented for this project. It is a long-standing practice in cryptography and high-assurance operations:

• Root CA key generation — Certificate Authorities create root signing keys in a scripted, witnessed, audited ceremony, under split knowledge and dual control, so no single person ever holds the whole key.
• DNSSEC Root KSK ceremony — ICANN runs a quarterly, publicly attested ceremony to sign the DNS root, with named role-holders (Crypto Officers, Internal Witnesses, a Ceremony Administrator).
• HSM / payment key ceremonies — banks and PCI-DSS environments load master keys into hardware security modules under dual control, with key components held by separate custodians.

The classic ceremony defends against a malicious or careless human insider. Our contribution is to extend the same primitives — split roles, dual control, verify-don't-view, fingerprint-only audit — to a new untrusted party: the AI/automation agent. The "Interactive Key Ceremony" treats a capable coding/ops agent the way a CA treats any single custodian: useful for everything around the secret, but never the holder of it. Framing it this way is deliberate — this is a known discipline applied to the agentic-operations threat surface, not a bespoke coinage.

9.1 Why this exists

A capable coding/ops agent is a force multiplier for everything except secret custody. The moment an agent can mint or read a production credential, that secret's blast radius includes the model's context window, the transcript, and any log it touches. The ceremony removes the agent from the secret path by construction — not by policy reminder — so the agent stays maximally useful (it writes the runbook, runs every verification probe, files the audit record) while the secret never enters a surface it shouldn't.

Three properties make it safe by construction, not by good behaviour:

1. The agent never executes the privileged write. A permission classifier blocks credential-minting commands; only the Security Human's interactive invocation runs it. A blocked mint is handed to the operator — never worked around.
2. The secret never enters the transcript. The new key's value is written straight to disk (~/.crm-*-key, chmod 600) or piped directly into wrangler secret put. Read-back surfaces return a masked preview (564bbe…9298) or a "(set)" flag — never the value.
3. Additive-only, verified-first. The agent reads the endpoint's source first to confirm the operation is additive (the rotatable key lives at KV admin_key:rotatable, alongside — never replacing — the root ADMIN_KEY), so a failed or interrupted ceremony can never orphan the root credential.

9.2 The ceremony flow

  ┌──────────────┐        ┌─────────────────────┐        ┌──────────────────┐
  │ SECURITY     │        │  AGENT               │        │ PERMISSION       │
  │ HUMAN        │        │  (AI / automation)   │        │ CLASSIFIER       │
  └──────┬───────┘        └──────────┬───────────┘        └────────┬─────────┘
         │                           │                             │
         │   1. "rotate the key"     │                             │
         │ ─────────────────────────▶│                             │
         │                           │  2. READ source first       │
         │                           │     (endpoint additive?     │
         │                           │      root untouched?)       │
         │                           │                             │
         │                           │  3. attempt the mint  ──────▶│
         │                           │                             │ 4. BLOCK
         │                           │◀──────  denied  ────────────│   (credential
         │                           │                             │    minting)
         │   5. agent hands command  │                             │
         │◀──── back to operator ────│                             │
         │                           │                             │
   6. RUN interactively              │                             │
   curl -X POST …/admin/rotate-key   │                             │
   -H "Authorization: Bearer         │                             │
      $(cat ~/.crm-admin-key)"       │                             │
         │                           │                             │
   7. response field ──▶ written     │                             │
      straight to ~/.crm-*-key       │                             │
      (chmod 600, never printed)     │                             │
         │                           │                             │
         │   8. "done"               │                             │
         │ ─────────────────────────▶│                             │
         │                           │  9. VERIFY (no secret seen): │
         │                           │   • GET /admin/rotate-key →  │
         │                           │     masked preview only      │
         │                           │   • probe real endpoint      │
         │                           │     (/admin/markets → 200)   │
         │                           │   • old key → 401 (dead)     │
         │                           │   • check rotations: N meta  │
         │                           │                             │
         │                           │ 10. RECORD audit entry       │
         │                           │     (fingerprint only,       │
         │                           │      no key value)           │
         ▼                           ▼                             ▼

9.3 The trust boundary (who-can-touch-what)

Every arrow that creates a secret is executed by the Human; every arrow that checks one is executed by the Agent. The root key never leaves the Cloudflare secret store — rotation happens one rung down (admin_key:rotatable), which is why a botched ceremony can't lock anyone out.

   ROOT  ── Cloudflare secret ─────────────  CLI only, Security Human, never moves
    │      (ADMIN_KEY)
    │  POST /admin/rotate-key  (Human runs interactively; Agent blocked)
    ▼
 ROTATABLE ── KV: admin_key:rotatable ─────  delegate / agency, self-rotates,
    │                                         root-revocable (DELETE)
    │  POST /admin/provision-token
    ▼
 TENANT (crm_t_*) ── KV per-shop ──────────  client B, shop-scoped, no admin access

   AGENT scope ▒▒▒▒  verify + record only — never mints, never holds a value

9.4 Audit record format

Every ceremony files one append-only record. It carries fingerprints, never secrets (sha256(value)[:8]), so the trail is itself safe to publish:

9.5 Operator rules (reaffirmed)

• Secrets only via $(cat ~/.file) — never inline, never printed, never committed.
• A classifier-blocked privileged command is handed to the operator (run interactively), not worked around or retried with the guard disabled.
• Source is read before any retry, to confirm the operation is additive and the root credential is untouched.
• Local key inventory lives in chmod 600 dotfiles (~/.crm-admin-key root, ~/.crm-agency-key delegate, per-market site tokens) — never in the repo, never in chat.
• Client (B) gets tenant token only — no admin access of any kind

9.6 Challenge & solution — .env files and the CLI as an AI exposure surface

The conventional way to manage secrets across Cloudflare, Shopify, and Xano — a .env file on disk plus a wrangler secret put typed at the terminal — is exactly the surface that leaks to an AI agent. The ceremony exists because these two everyday conveniences become liabilities the moment a capable agent shares the workstation.

The challenge (three concrete exposure vectors):

• .env is plaintext at rest. Any agent with file-read or shell access can cat it. Once read, the secret lives in the model's context window and the chat transcript permanently — it cannot be "un-seen."
• CLI arguments and stdin are capturable. A secret passed inline (wrangler secret put KEY <value>, or a curl -H "Authorization: Bearer sk_live_…") lands in shell history and in the tool-call log the agent can read back.
• Echo-back on "verify." The lazy way to confirm a key is to print it — which dumps the live value straight into context. Verification, not just storage, is an exposure point.

The solution (route every secret around the agent):

Net posture: the .env file and the CLI are treated as hostile-to-AI by default. The human is the only party that ever handles a secret's value; the agent is the only party that keeps the (value-free, fingerprint-only) audit trail. Usefulness of the agent is preserved; custody of the secret is structurally withheld from it.

9.7 Ceremony roles in an organization (RACI)

The two-role model (§9.2) is a minimum: one Security Human + one Agent. In a staffed organization those duties distribute across named functional roles. The table below maps each to the ceremony — and which existing actor in §9.2 it embodies.

Two persona dimensions apply:

• Organizational persona — an internal functional role on the delivering team (below). These are operators and approvers of the ceremony.
• Stakeholder persona — the external tier that receives the result: A (App Creator), B (Shared / tenant-token only), C (Private Worker), defined in §5 / §7. Organizational personas act on behalf of a stakeholder tier (typically A or C, since B never touches admin credentials).

**The Agent (AI/automation) maps to none of the human roles.** It prepares the runbook, runs the verification probes on the QA/Compliance officers' behalf, and files the fingerprint-only audit record — but never executes the privileged write and never holds a value (§9.1).

9.7.1 Segregation of duties (the point of dual control)

The compliance value only holds if the roles do not collapse into one person:

• The Deployment Officer (who executes) must not also be the Compliance Officer (who attests) — self-attestation defeats the audit. PCI-DSS dual control is precisely this separation.
• The DPO approves before execution; the Compliance Officer reviews after — approval and attestation are separate gates, held by separate people.
• In a small team, one person may wear several hats, but the executor and the attester must remain distinct, and the Agent always stays in the verify-and-record lane regardless of headcount. Documenting which human held which hat per ceremony is itself part of the audit record (executed_by vs verified_by, §9.4).

10. Formal Definitions (Regulated-Industry Glossary)

These are the normative, citable definitions a regulated deployment (PCI-DSS, SOC 2, GDPR, ISO 27001, FIPS-validated environments) will expect when auditing this lifecycle. Where this project's terms are colloquial (e.g. "blast radius"), the formal equivalent is given so the control maps cleanly to an assessor's framework.

Mapping note for assessors. §9 (Interactive Key Ceremony) is the implementation of dual control + SoD + least privilege, extended so that an AI/automation agent is treated as a non-custodial actor — it may verify and record but never satisfies the "authorized individual" requirement for the privileged write. §9.4 (audit record) satisfies non-repudiation; §8.1 (rotation schedule) satisfies cryptoperiod bounds.

11. Significance in Recent Shopify & Google GraphQL / Server-Side Migrations

The two platform migrations this stack rides on — Shopify REST → GraphQL Admin and Google UA → GA4 (server-side measurement) — are not just API churn. Both move credential-bearing work from many low-privilege, client-exposed identifiers to fewer, high-privilege, server-side secrets concentrated in the edge worker. That concentration is exactly what makes the key lifecycle in this document load-bearing rather than optional. See SHOPIFY-2026-RISK-BRIEF.md and FEATURE-SPEC-UA-MIGRATION.md.

11.1 Shopify: REST → GraphQL Admin API

• One endpoint, one token, broad surface. The GraphQL Admin API exposes a single endpoint (/admin/api/<version>/graphql.json) guarded by one Admin access token. The token's scope of compromise (§10) is now the entire granted schema — queries and mutations alike — not a single REST route. → Control: least-privilege scoping (request only the read_*/write_* scopes actually used) and disciplined rotation become the primary defenses, not an afterthought.
• Platform-native token rotation. Shopify Admin tokens are increasingly short-lived / expiring, and the worker auto-rotates them (§2, SHOPIFY_ADMIN_TOKEN). The platform's own direction now matches the cryptoperiod discipline of §8.1 — rotation is no longer a manual chore the org might skip.
• Server-side is mandatory, not optional. A GraphQL Admin token must never reach the browser; all calls run server-side in the Cloudflare worker. The worker becomes the credential boundary — which is precisely why the .env/CLI-as-AI-exposure threat model (§9.6) applies to the live system, and why the ceremony keeps the agent that generates GraphQL code out of secret custody.

11.2 Google: Universal Analytics → GA4 (server-side measurement)

• A real secret appears where there wasn't one. Client-side UA/gtag used only a public measurement ID (no secret). GA4 server-side measurement (Measurement Protocol / server-side tagging) requires a genuine api_secret (GA4_API_SECRET, §2). Measurement moving server-side moves the secret into the worker — a new custodial asset that must be set write-only and rotated.
• Consent-gated credentials. GA4 + Consent Mode v2 (required in the EEA for ad-personalization signals) couples credential use to a lawful-basis gate — bringing the DPO (§9.7, GDPR Art. 37–39) and security-of-processing (Art. 32, §10) into the key lifecycle, not just analytics config.
• Higher-trust data paths. GA4 Data API / BigQuery export use OAuth / service-account credentials whose scope of compromise includes historical analytics data — again favoring least-privilege scoping over broad, long-lived grants.

11.3 The common thread (why this document matters now)

Bottom line: GraphQL's single-endpoint model and Google's server-side measurement both concentrate credential power into fewer, server-resident secrets — at the same moment AI agents are doing more of the integration work. That intersection is the reason the Interactive Key Ceremony (formal dual control + SoD, extended to treat the agent as non-custodial) is the right — and arguably required — control for a regulated deployment of this stack.

12. Ownership — Who Owns This, From Tech to Business

The RACI model (defined in §10) requires that every activity have exactly one Accountable owner. This section names that owner end-to-end and shows how ownership escalates from the technical floor to the business.

Legend: R = Responsible (does it) · A = Accountable (owns the outcome, one only) · C = Consulted (input before) · I = Informed (told after).

12.1 The single point of accountability

• Business owner / Accountable for the lifecycle as a whole: the CISO (or, in a smaller org, the Head of Security / VP Engineering who carries the risk mandate). Accountability for risk is a business function — it cannot sit with an individual contributor or an outside consultant.
• Technical Accountable (delegated): the Engineering Lead for the mechanism itself — the worker, the KV/secret stores, the rotation endpoints. The CISO owns that the control works; the Engineering Lead owns how it works.
• The DPO is Consulted, never Accountable. GDPR's conflict-of-interest bar (§10) forbids the DPO from owning the processing decision; they advise and monitor.
• The Agent (AI/automation) never appears as A or R for a privileged write — only as a support actor for verification/recording (§9.1).

12.2 RACI across the lifecycle (tech → business)

Reading the chain: technical Responsibility concentrates on the Deployment Officer (execution) and Engineering Lead (mechanism); operational coordination on the PMO; assurance on QA and Compliance; lawful-basis advice on the DPO; and ultimate Accountability for risk on the CISO / business. Every row has exactly one A — the model's core invariant.

12.3 Smaller-org collapse (and the lines that must not collapse)

In a lean team one person may hold several letters, except the two invariants from §9.7.1: the executor (Deployment Officer) and the attester (Compliance Officer) must stay distinct, and Accountability (A) must sit with a business risk owner, not the person doing the work (R). If a single founder wears every hat, the Agent's non-custodial verify-and-record role becomes the de-facto second control — which is why the ceremony is designed to hold even at headcount = 1.

13. Self-Service Tenant Key Management (App Owners)

Added v1.5 (2026-07-03). The buyer-facing tier of the key hierarchy: every app purchase includes a dedicated per-store admin credential that the owner — not the platform — mints, rotates, revokes, and audits.

13.1 Position in the key hierarchy

The platform root and delegate tiers are covered by §§3–9. This section covers the third tier, which is the one sold with the product: the owner's dedicated key.

13.2 The owner lifecycle (wizard)

Owners manage their key through a guided wizard — sign in, confirm the store, generate. The design constraints mirror the ceremony's invariants, translated to self-service:

1. Entitlement-gated ownership. A signed-in identity may manage a store's keys only if its entitlement record — written by purchase, not self-serviceable — lists that store. A login alone never escalates to key access.
2. Shown once. The key value is returned exactly once at mint. Every subsequent view is a truncated fingerprint (sha256[:8]) and a masked preview. Losing the key means rotating it — by design, there is nothing to "look up."
3. Mint-before-revoke rotation. The replacement key is written before predecessors are deleted, so no failure mode leaves the store keyless (the self-service analogue of §9's additive-only rule).
4. Incident revoke. Any single key can be killed by fingerprint without a replacement — the owner's kill switch for a suspected leak.
5. Append-only audit. Every rotate/revoke appends a fingerprint-only record (date, action, actor, old → new fingerprints) to a per-store ledger the owner can read in the wizard — the same record shape a ceremony files (§9.5), produced automatically.

13.3 Session integrity underneath the wizard

The wizard is only as trustworthy as the login in front of it:

• Server-side logout revocation. Logging out denylists the session token at the server (hash, TTL = remaining token lifetime). A cached copy of the session — browser storage, history, a shared machine — dies with the logout instead of surviving to its natural expiry.
• Click-time token passing. Authenticated surfaces receive the session token at interaction time and hold it in memory; it is scrubbed from URLs and never persisted by the receiving page.

13.4 Why this is the product, not a feature

A SaaS contract asks the customer to trust the vendor's custody of credentials and a document's promise about it. This model inverts custody: the platform operates the key system — mint, rotation, revocation, audit — while the customer holds the key value. The operator cannot leak what it never held; the owner cannot be locked out of what only they possess. Peer teams extend the same property to their agents: agents act under scoped, revocable mandates and never hold the owner's key (§9.1's non-custodial rule, applied to the customer's own automation).