vignette/docs/ops/hanshin-data-governance-gate.md

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:

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.

# 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.