# Hanshin Data Governance and SSO Gate

## Purpose

This is the Phase 0/P1 entry evidence gate for Hanshin data access, consent scope,
and institutional SSO. It is an operations checklist, not legal advice and not an
approval record.

Do not mark this gate complete from assumptions. Every required row needs an owner,
evidence path, reviewer, date, and an explicit decision.

Primary evidence packet:

- `00-governance/hanshin-official-inquiry.pdf`
- `00-governance/hanshin-response.pdf`
- `00-governance/consent-scope-matrix.md`
- `00-governance/sso-claim-map.md`
- `00-governance/privacy-review.md`

## Gate Rule

P1 work may proceed only as a technical dry run until these external facts are
documented:

- Hanshin confirms the SSO protocol, test path, and released claims.
- The data steward confirms what source data can be supplied and under what
  consent scope.
- Minor/source-case data use has explicit lawful consent or a documented decision
  blocking that data from live use.
- Privacy review covers storage, retention, withdrawal, third-party model transfer,
  and any overseas transfer of masked text.

## Artifact Owners

| Artifact | Required owner | Required reviewer | Evidence field | Status |
| --- | --- | --- | --- | --- |
| Official inquiry letter | Project operator | Data steward | Letter path, sent_at, recipient | Pending |
| Hanshin written response | Hanshin contact | Project operator | Response path, received_at | Pending external evidence |
| Consent scope matrix | Data steward | Legal/privacy reviewer | Matrix path, consent form versions | Pending |
| SSO claim map | Auth owner | Hanshin IdP owner | Metadata path, sample claims, test result | Pending |
| Privacy review | Legal/privacy reviewer | Data steward | Review path, decision, open issues | Pending |

## Official Inquiry Questions

Use these questions in the official inquiry packet. Keep answers as written evidence;
do not paraphrase verbal answers as approval.

| Area | Question | Owner | Evidence required | Live gap if missing |
| --- | --- | --- | --- | --- |
| SSO protocol | Does Hanshin require OIDC/OAuth, SAML 2.0, both, or neither for this pilot? | Auth owner | Written response plus IdP metadata or OIDC discovery URL | Cannot finalize provider implementation |
| SSO test access | Is there a test tenant, test account, or staged IdP path? | Auth owner | Test account procedure without secrets in repo | Cannot prove live login flow |
| Claim release | Which claims/attributes are released for learners, instructors, and admins? | Auth owner | Sample decoded claims or SAML attribute statement with values redacted | RBAC mapping remains speculative |
| Identifier stability | Which claim is the stable user key across semesters and role changes? | Data steward | Written statement naming the claim | Account linking risk |
| Role source | Where do instructor/admin roles come from: IdP groups, roster import, or manual approval? | Data steward | Role source decision and evidence path | Privilege model cannot go live |
| Domain policy | Which email domains are eligible and how are alumni/contractors handled? | Data steward | Domain list and exception process | Admission policy incomplete |
| Deprovisioning | How quickly are withdrawn or ineligible users removed from SSO/roster access? | Data steward | Deprovisioning SLA or operating procedure | Access removal evidence gap |
| Source transcripts | How many additional transcripts or session records can Hanshin provide, and in what form? | Data steward | Dataset inventory, counts, date range, allowed fields | n=1 dataset risk remains |
| Minor/source-case consent | Does existing consent cover AI learning, secondary processing, DB retention, and derived artifacts? | Legal/privacy reviewer | Consent form versions and review decision | Source-case data blocked |
| Guardian consent | If source-case data includes minors, is guardian consent present for each requested use? | Legal/privacy reviewer | Consent receipt index, no identities in repo | Minor data blocked |
| Raw data handling | May raw transcripts/audio be stored, or only masked/transformed text? | Data steward | Handling rule and storage location | Raw ingestion blocked |
| Third-party inference | May masked text be sent to external model providers for feedback or evaluation? | Legal/privacy reviewer | Transfer review and provider list | External calls limited or blocked |
| Overseas transfer | Are overseas transfer notices or separate consent required for masked text leaving Korea? | Legal/privacy reviewer | Review decision and notice/consent version | Overseas provider use blocked |
| Retention | What retention, deletion, and archival periods apply to source data, pilot data, logs, and exports? | Data steward | Retention schedule | No live storage approval |
| Withdrawal | What happens after participant or source-case consent withdrawal? | Data steward | Withdrawal runbook and limitation notes | Export/KPI use blocked |

## Consent Scope Checklist

Create `00-governance/consent-scope-matrix.md` with one row per consent form version
and data source. Mark unknowns as `blocked`, not `approved`.

| Scope item | Required decision | Owner | Evidence | Current gate status |
| --- | --- | --- | --- | --- |
| Trainee account creation and login | Required for pilot user access | Data steward | Consent or participation notice version | Pending |
| Session text storage | Required before storing trainee sessions | Legal/privacy reviewer | Consent text and retention rule | Pending |
| Supervisor/instructor review | Required before instructor dashboard use | Data steward | Consent text and RBAC procedure | Pending |
| KPI reporting | Required before pilot metrics | Data steward | Consent text and aggregation rule | Pending |
| Recursive learning seed export | Separate opt-in or documented lawful basis required | Legal/privacy reviewer | Consent version and export limitation | Pending |
| Source transcript reuse | Required before importing Hanshin source cases | Data steward | Source inventory and consent review | Pending |
| Minor/source-case AI learning | Separate guardian/legal basis decision required | Legal/privacy reviewer | Consent receipt index or block decision | Pending external evidence |
| Raw audio storage | Separate decision required; default blocked | Data steward | Audio retention and access control rule | Blocked until approved |
| Third-party model processing | Required before sending text to any model provider | Legal/privacy reviewer | Provider/field list and transfer review | Pending |
| Overseas transfer notice | Required if provider processing leaves Korea | Legal/privacy reviewer | Notice/consent version or legal memo | Pending external evidence |
| Withdrawal after participation | Required before live pilot | Data steward | Withdrawal log procedure and limits | Pending |
| Identity map handling | Required before roster import | Auth owner | Storage location, access owner, no repo storage | Pending |

Minimum fields for each matrix row:

```text
source_or_consent_version:
scope_item:
decision: approved | blocked | needs_review
allowed_data_fields:
blocked_data_fields:
retention_rule:
withdrawal_rule:
owner:
reviewer:
evidence_path:
reviewed_at:
open_issues:
```

## SSO, OAuth, and SAML Claim Mapping

This table separates user login SSO from engine/provider OAuth tokens. Engine OAuth
or CLI credentials are out of scope for institutional identity and must not be used
as user identity evidence.

| App field | OIDC/OAuth claim | SAML attribute | Required | Owner | Evidence required | Gap if missing |
| --- | --- | --- | --- | --- | --- | --- |
| `auth_subject` | `sub` | persistent `NameID` or configured immutable ID | Yes | Auth owner | Redacted sample claim and stability statement | Cannot link accounts safely |
| `email` | `email` | `mail` or equivalent | Yes | Auth owner | Redacted sample claim | Cannot identify eligible domain |
| `email_verified` | `email_verified` | IdP assurance statement or verified mail attribute | Yes for OIDC | Auth owner | Claim sample or IdP policy | Email trust unresolved |
| `email_domain` | `hd` or parsed domain | derived from `mail` | Yes | Data steward | Domain eligibility list | Domain gate speculative |
| `display_name` | `name` | `displayName` | Optional | Auth owner | Claim sample | UI may use fallback |
| `given_name` | `given_name` | `givenName` | Optional | Auth owner | Claim sample | UI may use fallback |
| `family_name` | `family_name` | `sn` | Optional | Auth owner | Claim sample | UI may use fallback |
| `institution_user_id` | custom claim if available | `employeeNumber`, `studentNumber`, or equivalent | Preferred | Data steward | Attribute release approval | Roster matching weaker |
| `role_source` | `groups`, custom role claim, or roster import | `memberOf`, eduPerson affiliation, or roster import | Yes | Data steward | Role mapping decision | RBAC cannot go live |
| `cohort_or_department` | custom claim or roster import | department/cohort attribute or roster import | Preferred | Data steward | Mapping rule | Instructor scope incomplete |
| `auth_method` | `acr`/`amr` if available | AuthnContextClassRef | Optional | Auth owner | IdP policy | Cannot assert MFA/assurance |
| `session_expires_at` | `exp` plus app session TTL | SAML session index/session TTL | Yes | Auth owner | TTL policy and test result | Session risk unresolved |

Required SSO evidence files:

- IdP metadata or OIDC discovery document location.
- SP/client configuration record with secrets redacted.
- Redacted successful login claim sample for learner.
- Redacted successful login claim sample for instructor/admin if roles are IdP-backed.
- Negative authorization test showing an ineligible account is denied.
- Logout/deprovisioning behavior note.

## Live and External Evidence Gaps

The following are not currently proven by repository code or local docs and must stay
open until external evidence is attached:

| Gap | Blocks | Required close-out evidence |
| --- | --- | --- |
| Hanshin SSO protocol is not confirmed | Production SSO selection | Written response plus metadata/discovery URL |
| Released SSO claims are not confirmed | RBAC and account linking | Redacted claim samples and mapping approval |
| Instructor/admin role source is not confirmed | `/teach` and admin live access | Role source decision and authorization test |
| Additional transcript supply is not confirmed | Dataset expansion beyond seed data | Dataset inventory with allowed fields and counts |
| Minor/source-case consent scope is not confirmed | Any source-case import or recursive learning use | Consent review decision or explicit block decision |
| Overseas/third-party model transfer review is not complete | External model calls with real data | Privacy review naming providers, fields, and transfer basis |
| Withdrawal and retention rules are not signed | Pilot launch and export generation | Signed runbook, retention schedule, and withdrawal log path |

## Evidence Packet Template

Create the packet outside the repository if it contains identities, secrets, raw
transcripts, or signed forms. Store only redacted summaries or paths here.

```markdown
# Hanshin Data Governance Evidence Packet

Packet ID:
Evidence root:
Prepared by:
Data steward:
Legal/privacy reviewer:
Auth owner:
Review date:

## Decisions
- SSO protocol:
- User identifier claim:
- Role source:
- Allowed email domains:
- Source data allowed:
- Minor/source-case data decision:
- Third-party model transfer decision:
- Retention and withdrawal decision:

## Attached Evidence
- Official inquiry:
- Hanshin response:
- IdP metadata/discovery:
- Redacted claim samples:
- Consent forms reviewed:
- Privacy review:
- Dataset inventory:
- Withdrawal runbook:

## Open Issues
- 

## Decision
- [ ] Approved for technical dry run only.
- [ ] Approved for live pilot with listed limits.
- [ ] Blocked pending external evidence.
```

## Exit Criteria

This gate is closed only when:

- Every required artifact owner and reviewer is named.
- Evidence paths exist for the official inquiry, written response, consent matrix,
  SSO claim map, and privacy review.
- Live gaps above are either closed with evidence or explicitly converted into
  launch blockers.
- No raw identities, secrets, signed consent forms, raw transcripts, cookies, or
  tokens are committed to the repository.