--- id: WF-PFM-INT-005 title: Keep credentials current trigger: The initiating scheduler starts this flow. product_area: platform module: integrations revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 implements: - CAP-PFM-INT-005 - CAP-PFM-INT-006 moves: - STATE-PFM-INT-003 - STATE-PFM-INT-004 crosses: [] idempotency: 'Tokens no longer due are skipped, and recorded expiry-warning metadata suppresses repeated notices.' concurrency: A per-connection refresh lock prevents concurrent refreshes from duplicating the token request. hops: - 'n': 1 actor_or_service: Scheduler action: 'Run token refresh each minute and credential maintenance daily at 06:17 UTC.' anchor: 'services-platform:modules/integrations/aws/logic/integrations-credentials.schedule.ts' seam: schedule on_failure: A later scheduled pass revisits due work; silence and failure metrics reveal missed work. left_inconsistent: Credentials can expire while processing is delayed. observer: Operations alarms provenance: documented source: 'services-platform:docs/integrations/README.md#The pieces' - 'n': 2 actor_or_service: Credential refresh pass action: >- Refresh tokens that expire within ten minutes for each operational workspace, taking the connection refresh lock. anchor: >- services-platform:modules/integrations/services/credentials/credential-passes.ts:runCredentialRefreshPass seam: sync on_failure: Credential refusal requires reauthorization; other refresh errors wait for a later pass. left_inconsistent: A temporary provider failure can leave a token near expiry. observer: Refresh failure alarm provenance: observed source: >- services-platform:modules/integrations/services/credentials/credential-passes.ts:runCredentialRefreshPass - 'n': 3 actor_or_service: Integrations service action: 'Commit reauthorization status and binding invalidation, then request administrator mail.' anchor: >- services-platform:modules/integrations/services/connections/transition.ts:requireConnectionReauthorization seam: sync on_failure: Mail failure is recorded in logs without undoing the transition. left_inconsistent: The account remains blocked even if its administrators are not notified. observer: Needs Attention provenance: observed source: >- services-platform:modules/integrations/services/connections/transition.ts:requireConnectionReauthorization - 'n': 4 actor_or_service: Credential maintenance pass action: >- Confirm destroyed secrets, record one warning per near refresh-token expiry and remove authorization states abandoned for a day. anchor: >- services-platform:modules/integrations/services/credentials/credential-passes.ts:runCredentialMaintenancePass seam: sync on_failure: Log a workspace failure and continue the pass. left_inconsistent: Cleanup metadata can lag secret-storage deletion. observer: Maintenance silence alarm provenance: observed source: >- services-platform:modules/integrations/services/credentials/credential-passes.ts:runCredentialMaintenancePass evidence: - >- services-platform at ad3f6a65: modules/integrations/aws/logic/integrations-credentials.schedule.ts; services/credentials/credential-passes.ts, refresh.ts; services/notices/connection-notices.ts - >- services-platform:modules/integrations/tests/integration/services/credentials/refresh.integration.spec.js#makes one token request when two refreshes of a connection run at once - >- services-platform:modules/integrations/tests/integration/services/connections/connection-feature-changes.integration.spec.js#INT-ACC-0113 step 3: the loss tells each administrator of the tenant once, two notices in all, each with the features-lost subject - >- services-platform:modules/integrations/tests/integration/services/credentials/credential-maintenance.integration.spec.js#sends nothing and audits nothing more on the next day’s pass for the same expiry controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Keep credentials current ## What It Does Scheduled refresh keeps sign-in credentials usable, while daily maintenance reconciles secret deletion, upcoming refresh-token expiry and abandoned authorization state. A provider refusal changes account eligibility. Administrator email follows the committed change as a best-effort notice. ## The Flow ```mermaid sequenceDiagram participant P0 as Scheduler participant P1 as Credential refresh pass participant P2 as Integrations service participant P3 as Credential maintenance pass P0->>P0: 1. Run token refresh each minute and credential maintenance daily at 0617 UTC. P1->>P1: 2. Refresh tokens that expire within ten minutes for each operational workspace P2->>P2: 3. Commit reauthorization status and binding invalidation P3->>P3: 4. Confirm destroyed secrets ``` ## When Something Fails A later scheduled pass revisits due work; silence and failure metrics reveal missed work. Credentials can expire while processing is delayed. Credential refusal requires reauthorization; other refresh errors wait for a later pass. A temporary provider failure can leave a token near expiry. Mail failure is recorded in logs without undoing the transition. The account remains blocked even if its administrators are not notified. Log a workspace failure and continue the pass. Cleanup metadata can lag secret-storage deletion. ## Open Design Questions The rotation-date branch is dormant because no examined writer supplies its trigger. Notification delivery remains best effort.