Handoff: SVC-003-iam-backfill-cutover-hardening iam-service backfill and cutover hardening

Scope

• Service/area: iam-service
• Task pack: docs/agents/service-tasks/iam-service.md
• Goal: accept the bounded IAM ownership and cutover-hardening evidence while keeping default auth/profile route promotion gated.
• Non-goals: default /api/auth* promotion, populated production target backfill approval, live data migration, Profile ownership work, auth-service recreation, broad user-service work, or changes to legacy source under /Users/velikho/Desktop/WORKING/HOCTAPAZ/.

Docs Read

• go-platform/docs/architecture/service-responsibility-matrix.md
• go-platform/docs/agents/service-agent-execution-queue.json
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-tasks/iam-service.md
• go-platform/docs/agents/agent-handoff-format.md
• go-platform/docs/api/iam-service.md
• go-platform/docs/qa/auth-route-live-smoke.md
• go-platform/docs/qa/auth-route-browser-smoke.md
• go-platform/docs/qa/iam-profile-route-rollback-rehearsal.md
• go-platform/services/iam-service/README.md

Legacy Evidence Read

• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/auth/auth.controller.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/src/modules/auth/auth.service.ts
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/api/prisma/schema.prisma
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/web/components/account/profile-settings-client.tsx
• /Users/velikho/Desktop/WORKING/HOCTAPAZ/node-platform/apps/web/lib/client-api.ts
• Legacy source was read-only evidence only; no legacy files were changed.

Files Changed

• go-platform/docs/agents/handoffs/SVC-003-iam-backfill-cutover-hardening.md
• go-platform/docs/agents/service-agent-closeout-ledger.json
• go-platform/docs/agents/service-agent-closeout-ledger.md

Behavior Implemented

• none in this handoff.
• Existing audited IAM implementation owns register/login/refresh/logout/me, password change/reset, Google Auth, JWT/JWKS, roles, permissions, access scopes, invites, organization membership, local security events, audit projection, school membership sync, and UUID shadow/backfill migration foundations.
• Existing repository and HTTP tests cover IAM permission and membership workflows, access-scope behavior, management guards, internal service-token guards, audit redaction/projection, school read-model sync, password reset/change, Google Auth, and UUID shadow validation paths.
• Existing route guard evidence keeps auth-service absent as a deployable service boundary. /api/auth* and /v1/auth* remain compatibility namespaces backed by iam-service.

Tests And Verification

• Command: GOTOOLCHAIN=go1.25.11 go test ./services/iam-service/... -count=1
• Result: passed.
• Evidence: iam-service command, audit sink, HTTP, repository, school sync, and usecase packages passed.
• Command: make test-auth-routes
• Result: passed.
• Evidence: default auth route table stayed legacy; auth-native route examples passed; live, browser, session-browser, and IAM/Profile rollback smoke scripts passed self-test mode.
• Command: make test-organization-routes
• Result: passed.
• Evidence: organization read route examples and IAM-owned membership write route examples passed route coverage while default organization writes stayed guarded.
• Command: ruby -e 'require "yaml"; ARGV.each { |path| YAML.load_file(path); puts "ok #{path}" }' services/iam-service/api/openapi.yaml contracts/openapi/services/iam-service.yaml && diff -u services/iam-service/api/openapi.yaml contracts/openapi/services/iam-service.yaml
• Result: passed.
• Evidence: IAM service OpenAPI and mirrored contract parsed and matched exactly.

Route State

• Legacy route: deploy/gateway/routes.json remains the default rollback table and keeps broad /api/auth, /api/admin, and fallback routes on legacy_proxy.
• Native route: deploy/gateway/routes.auth-native-example.json, deploy/gateway/routes.auth-native-localhost-example.json, and organization membership write examples remain non-default rehearsals.
• Gateway state: this handoff accepts IAM service-side and non-default route guard evidence only; it does not promote default public auth/profile routes.
• Rollback: keep deploy/gateway/routes.json active. If a non-default auth-native table is used for rehearsal, switch GATEWAY_ROUTE_TABLE back to deploy/gateway/routes.json to roll back to legacy.

Data Notes

• Tables touched: none in this handoff run.
• Migration run: none against a live database in this handoff.
• Validation report: not applicable because no live data was migrated or backfilled.
• Existing service migrations include IAM UUID shadow, FK validation, and primary-key promotion scaffolding; populated-target validation remains gated by the IAM/Profile cutover task packs.

Risks / Blockers

• This is closeout-accepted-cutover-gated-not-complete, not completion of the full IAM/Profile cutover.
• Optional Postgres integration commands requiring IAM_SERVICE_POSTGRES_TEST_DATABASE_URL were not run in this handoff because no DSN was configured for this turn.
• Fresh real gateway/browser runs were not rerun in this handoff; current docs retain latest local artifacts from 2026-07-09.
• Default route promotion still requires populated target proof, candidate diff/review, browser proof, rollback proof, and coordination with profile-service.

Next Step

• Close the matching SVC-004 profile-service cutover-gated handoff, then audit RET-USER so the deprecated user-service scaffold cannot receive new identity/profile work.