diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..69ef4e6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,226 @@ +# identity-canon — Agent Instructions + +## Repo Identity + +**Purpose:** Orthogonal vocabulary and canonical model for identity-related concepts. + +**Domain:** canon +**Repo slug:** identity-canon +**Topic ID:** `fe2aaa78-9c20-4feb-b3d2-4fe0529572a3` +**Workplan prefix:** `IDENTITY-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workstreams for this domain +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=fe2aaa78-9c20-4feb-b3d2-4fe0529572a3&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=identity-canon&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +2. Check inbox: `GET /messages/?to_agent=identity-canon&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. Note for the custodian operator: after workplan file changes, run from + `~/state-hub`: + ```bash + make fix-consistency REPO=identity-canon + ``` + This syncs task status from files into the hub DB. + +--- + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/IDENTITY-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-IDENTITY-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: IDENTITY-WP-NNNN +type: workplan +title: "..." +domain: canon +repo: identity-canon +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: IDENTITY-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=identity-canon` + (or send a message to the hub agent via `POST /messages/`) + +--- + +## Local Developer Workflow + +This repository is currently documentation-only. There is no package manifest, +runtime application, build system, executable test suite, or formatter/linter +configuration checked in. + +### Install + +No install step is required for normal repository work. + +### Build + +No build step exists. Treat Markdown and workplan edits as source artifacts. + +### Test / lint + +There is no project test runner or markdown linter configured yet. Use these +checks before closing a change: + +```bash +# Confirm the repository file inventory still looks intentional +rg --files + +# Catch whitespace errors in tracked and staged diffs +git diff --check +``` + +When workplan files change, sync ADR-001 file state into State Hub: + +```bash +curl -s -X POST "http://127.0.0.1:8000/repos/identity-canon/sync?fix=true" \ + | python3 -m json.tool +``` + +If the HTTP sync endpoint is unavailable, run the consistency script from the +State Hub checkout: + +```bash +cd ~/state-hub +.venv/bin/python scripts/consistency_check.py --repo identity-canon --fix +.venv/bin/python scripts/consistency_check.py --repo identity-canon +``` + +The generated instruction in older workplans says `make fix-consistency +REPO=identity-canon`; that is still valid when `uv` is installed and on PATH. +On this workstation, the `.venv/bin/python` fallback has been verified. + +### Run + +There is no local service to run from this repository. + +### Documentation Review Checklist + +- Keep `INTENT.md`, `SCOPE.md`, and `ResearchProposal.md` aligned on the + repository's research-only boundary. +- Keep source-backed observations in `research/` and canonical candidate terms + in `terminology/`, `canon/`, `model/`, and `scenarios/`. +- Mark draft concepts as candidate or draft until source notes contain real + references and extracted terminology. +- Record implementation ideas in `DownstreamRecommendations.md`, not as code in + this repository. diff --git a/DownstreamRecommendations.md b/DownstreamRecommendations.md new file mode 100644 index 0000000..71ff9e8 --- /dev/null +++ b/DownstreamRecommendations.md @@ -0,0 +1,34 @@ +# Downstream Recommendations + +Status: draft. This file captures implementation ideas derived from the canon +without moving implementation work into this repository. + +## Recommended Consumption Pattern + +Downstream repositories should consume identity-canon as a conceptual reference. +They should map their schemas, APIs, CLI commands, UI labels, and authorization +policies to canonical terms, but they should not depend on this repository as a +runtime package unless a later explicit package is extracted. + +## Near-Term Recommendations + +- When designing user-management schemas, separate Natural Person, Account, + Profile, Credential, and Principal fields. +- When designing tenant-aware systems, model Tenant as a scope and relate it to + Organization, Customer, Vendor, and Realm explicitly. +- When designing organization features, do not reuse Group or Role as a generic + replacement for Organization. +- When designing authorization adapters, treat Principal and relationship + tuples as projections from canonical actors, accounts, and relationships. +- When designing account-linking features, store Synonymity Assertions with + source, evidence, confidence, scope, lifecycle state, and privacy controls. +- When designing UI copy, use product-friendly labels but maintain internal + mappings to canonical concepts. + +## Avoid For Now + +- Do not implement identity provider integrations in this repository. +- Do not add database migrations or production APIs here. +- Do not treat this glossary as a finalized schema. +- Do not use `user` as a canonical table, API, or class name without a mapping + note that explains which canonical concept it represents. diff --git a/OpenQuestions.md b/OpenQuestions.md new file mode 100644 index 0000000..27a3b4b --- /dev/null +++ b/OpenQuestions.md @@ -0,0 +1,35 @@ +# Open Questions + +Status: draft. These questions are intentionally non-secret and +implementation-neutral. + +## Canon Questions + +- Should Realm stay a Scope specialization, or does it need its own canonical + concept because of issuer and federation semantics? +- Should Customer Account become a canonical concept, or should customer + account records remain downstream commercial modeling? +- Should Team be modeled as a Group, Organization Unit, Community, or a + separate specialization? +- Should Legal Entity be a specialization of Organization or a relationship + between an Organization and a legal system? +- What fields are mandatory for every Relationship versus only for sensitive + relationships such as delegation, representation, and synonymity? + +## Synonymity Questions + +- Which confidence vocabulary should be used for weak matches? +- What is the minimum evidence model for strong account links? +- How should revocation or expiry of a synonymity assertion affect downstream + caches? +- How should privacy-limited links be represented so accidental broadening is + visible during review? + +## Corpus Questions + +- Which source notes should be backfilled first: SCIM and LDAP for record + semantics, OIDC and SAML for subject semantics, or OpenFGA and Cedar for + authorization projections? +- How much product-specific detail belongs in source notes versus downstream + recommendations? +- What citation format should the repo use once source notes are populated? diff --git a/README.md b/README.md index 70d07ec..1693ac6 100644 --- a/README.md +++ b/README.md @@ -1 +1,12 @@ -Othogonal vocabulary and canonical model for identity related concepts. \ No newline at end of file +# identity-canon + +Orthogonal vocabulary and canonical model for identity-related concepts. + +Start with: + +- `INTENT.md` for purpose and project boundaries; +- `ResearchProposal.md` for the research method and expected deliverables; +- `research/CorpusIndex.md` for the source-note corpus; +- `canon/CanonicalGlossary.md` and `model/ConceptualModel.md` for the current + draft canon; +- `workplans/` for State Hub-tracked work. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..359c8a7 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,54 @@ +# SCOPE + +## One-liner + +Orthogonal vocabulary and canonical model for identity-related concepts. + +## Core Idea + +`identity-canon` is a research and terminology repository. It defines an +implementation-neutral vocabulary and conceptual model for identity, accounts, +actors, organizations, tenants, communities, families, agents, relationships, +and synonymity across IAM, directory, federation, social graph, authorization, +decentralized identity, and entity-resolution domains. + +## In Scope + +- Maintain research notes, source summaries, terminology inventories, + conflict maps, canonical glossary entries, conceptual model notes, scenario + tests, open questions, downstream recommendations, and State Hub workplans. +- Compare overlapping terms across standards, product documentation, social + graph models, authorization systems, and privacy/entity-resolution research. +- Keep canonical definitions separate from external product mappings. +- Record decisions, progress, and workplan status through State Hub. +- Verify changes with markdown review, `git diff --check`, and ADR-001 + consistency checks. + +## Out of Scope + +- Implement identity providers, account-management services, provisioning + adapters, authorization engines, UI components, CLI commands, databases, or + production APIs. +- Own unrelated adjacent systems or operational identity lifecycle tooling. +- Make irreversible operational decisions without human approval. +- Treat draft canon artifacts as finalized schemas before source-note backfill + and scenario review. + +## Current State + +- Status: active research scaffold. +- The repository is currently documentation-only. It has no package manifest, + build system, runtime app, or executable test suite. +- `IDENTITY-WP-0002` seeded the first terminology, canon, model, scenario, + open-question, and downstream recommendation artifacts. The next research + pass should backfill individual source notes and revise the draft canon from + evidence. + +## Getting Oriented + +- Start with: INTENT.md +- Research proposal: ResearchProposal.md +- Corpus index: research/CorpusIndex.md +- Draft canon: canon/CanonicalGlossary.md and model/ConceptualModel.md +- Agent instructions: AGENTS.md +- Workplans: workplans/ diff --git a/canon/CanonicalGlossary.md b/canon/CanonicalGlossary.md new file mode 100644 index 0000000..1d0ae01 --- /dev/null +++ b/canon/CanonicalGlossary.md @@ -0,0 +1,251 @@ +# Canonical Glossary + +Status: draft. These definitions are initial candidate canon terms. They are +intended to be challenged by source-note backfill and scenario testing. + +## Actor + +An entity that can participate in relationships, hold or control accounts, be +represented by another actor, or be projected into downstream systems. + +Includes: natural persons, organizations, communities, families, service +accounts, bots, and AI agents. + +Excludes: raw identifiers, credentials, claims, and profiles unless they are +being represented as records about an actor. + +## Natural Person + +A human being. A natural person may have many accounts, profiles, identifiers, +credentials, personas, and relationships. + +Excludes: account records, social profiles, legal entities, and artificial +agents. + +## Artificial Agent + +A non-human actor that performs actions under software, automation, or delegated +control. + +Includes: bots, service agents, workloads, and AI agents. + +## Collective Actor + +An actor composed of or associated with multiple actors. + +Includes: organizations, communities, families, households, groups, and teams +when they can participate in relationships or be represented. + +## Account + +An operational record in a scope that enables access, login, administration, or +system participation. + +Includes: human login accounts and service accounts. + +Excludes: natural persons, billing accounts, profiles, credentials, and +authorization principals unless a source uses account in that narrower context. + +## Service Account + +An account intended for software, workload, bot, or automation access rather +than ordinary human interactive use. + +## Identity Record + +A record that describes, binds, or organizes information about an actor within +a source or scope. + +Identity Record is deliberately narrower than bare `identity`; it is a record, +not selfhood, not proof material, and not necessarily a login account. + +## Identifier + +A value or reference used to distinguish or refer to something within a scope. + +Examples: username, email address, LDAP DN, OIDC subject, SAML NameID, DID, +employee number, external source ID. + +## Scoped Identifier + +An identifier whose meaning is intentionally limited to a relying party, +sector, tenant, realm, application, namespace, or other scope. + +## Credential + +Evidence or secret material used to prove control, entitlement, or a claim. + +Examples: password, passkey, certificate, hardware token, verifiable +credential, recovery code, signed assertion. + +## Claim + +A statement made by an issuer or source about an actor, account, identifier, +relationship, or attribute. + +## Authenticated Subject + +The protocol-level representation of an entity after an issuer or identity +provider identifies it for a relying party. + +Examples: OIDC subject, SAML subject. + +## Authorization Principal + +The entity considered by an authorization system when evaluating whether an +action is allowed. + +## Profile + +A presentation or attribute surface for an actor or account in a scope. + +Examples: public social profile, local application profile, directory profile. + +## Persona + +A deliberate contextual presentation of an actor, often used to separate roles, +audiences, privacy boundaries, or pseudonymous participation. + +## Scope + +A boundary within which identifiers, meanings, relationships, accounts, +policies, or lifecycle states are valid. + +Examples: tenant, realm, relying party, namespace, application, community, +authorization domain. + +## Tenant + +An administrative or isolation scope for a system, service, platform, or +application. + +A tenant may be associated with an organization, customer, vendor, or community, +but it is not automatically identical to any of them. + +## Realm + +An issuer, security, or administrative namespace used by an identity system. + +Candidate status: treat Realm as a Scope specialization unless source analysis +shows it needs a separate canonical role. + +## Organization + +A collective actor with operational, social, administrative, or structural +continuity. + +Excludes: tenant, customer, and legal entity unless those meanings are modeled +as separate relationships or specializations. + +## Legal Entity + +An organization or other actor recognized by a legal system. + +## Customer + +An actor in a commercial or service-consumption relationship. + +Customer is a relationship role, not automatically a tenant or organization. + +## Vendor + +An actor in a service-provider relationship. + +Vendor is a relationship role, not automatically a tenant or organization. + +## Community + +A collective actor formed around participation, affiliation, identity, interest, +moderation, or social interaction. + +## Family Or Household + +A collective actor or relationship network involving family, guardian, +dependent, household, or care relationships. + +This concept is privacy-sensitive and may have legal implications outside the +canon's scope. + +## Group + +A named collection of actors or accounts in a scope. + +Group membership may have authorization implications, but a group is not the +same concept as a role, community, team, or organization. + +## Role + +A named capability bundle, responsibility, or relationship label within a +scope. + +Roles may be assigned through memberships or relationships, but role is not +identical to group. + +## Relationship + +A typed, scoped assertion connecting one actor, account, identifier, group, or +other model element to another. + +Recommended fields: source, target, type, scope, evidence, issuer or source, +confidence when relevant, lifecycle state, and authorization implications. + +## Membership Relationship + +A relationship indicating that an actor or account belongs to, participates in, +or is accepted by a collective actor or scope. + +## Affiliation Relationship + +A relationship indicating association without necessarily implying membership, +control, employment, or authorization. + +## Following Relationship + +A directed social relationship where one actor subscribes to, follows, or +observes another actor or profile. + +## Representation Relationship + +A relationship where one actor acts or speaks on behalf of another actor within +a scope. + +## Delegation Relationship + +A relationship where one actor grants bounded authority to another actor. + +## Administration Relationship + +A relationship where one actor has management authority over accounts, +relationships, policies, or configuration in a scope. + +## Trust Relationship + +A relationship where one actor, issuer, verifier, system, or scope relies on +another for claims, identifiers, credentials, or decisions. + +## Synonymity Assertion + +A scoped, evidenced assertion that two or more identifiers, records, accounts, +profiles, or actors refer to the same target for a stated purpose. + +Synonymity assertions may be weak, strong, verified, inferred, revoked, +privacy-limited, or source-specific. + +## Evidence Source + +A source, document, event, issuer, import, observation, or verification process +supporting a claim, relationship, or synonymity assertion. + +## Lifecycle State + +The current state of a record, account, relationship, credential, claim, or +assertion. + +Examples: proposed, active, suspended, revoked, expired, archived, deleted, +superseded. + +## Non-Canonical Convenience Term: User + +`User` may be used in prose when quoting or mapping external systems, but it +should not be a canonical root concept. Resolve it to a specific canonical +concept before using it in model definitions. diff --git a/canon/DesignPrinciples.md b/canon/DesignPrinciples.md new file mode 100644 index 0000000..a34257b --- /dev/null +++ b/canon/DesignPrinciples.md @@ -0,0 +1,75 @@ +# Design Principles + +Status: draft. These principles make the proposal's modeling stance explicit. +They are constraints for canonical vocabulary and conceptual model work, not +implementation requirements for downstream systems. + +## P1. Use Actor As The Participation Root + +Do not start the model with `user`. An Actor is anything that can participate +in relationships, hold accounts, be represented, or be evaluated by downstream +systems. Natural persons, organizations, communities, families, and artificial +agents can all be actors. + +## P2. Keep Person, Account, Identity, Profile, And Principal Separate + +A natural person is not an account. An account is not a profile. A profile is +not a credential. A principal is an authorization projection. A subject is an +issuer-bound protocol view. These distinctions prevent the most common identity +model collapse. + +## P3. Treat Scope As First Class + +Identifiers, accounts, relationships, roles, policies, and meanings are only +stable within a scope. A scope may be a tenant, realm, relying party, sector, +community, application, namespace, or authorization domain. + +## P4. Model Collective Actors Without Collapsing Them + +Organizations, legal entities, customers, vendors, communities, families, +households, groups, and teams are not interchangeable. They may relate to each +other, but each should keep its social, legal, operational, or commercial +meaning visible. + +## P5. Model Relationships Explicitly + +Membership, affiliation, following, ownership, representation, delegation, +administration, employment, guardianship, and trust are separate relationship +types. Do not hide them inside groups, roles, or ad hoc attributes. + +## P6. Keep Authorization Projections Separate + +Authorization engines need principals, resources, actions, roles, policies, and +relationship tuples. These are projections from the conceptual identity model, +not the whole identity model. + +## P7. Treat Synonymity As An Assertion + +Weak matches, verified links, same-as claims, and merges are different. The +canon should represent synonymity as a scoped, evidenced, revocable assertion +with confidence and method, never as an automatic destructive merge. + +## P8. Preserve Source And Evidence + +Source systems, issuers, import jobs, operators, documents, and verification +events matter. Claims and relationships should be traceable to evidence or +source references when the model depends on them. + +## P9. Prefer Orthogonal Concepts Over Product Terms + +External systems are mapping targets, not the source of canonical truth. If a +product calls something a user, organization, group, project, tenant, or realm, +the canon should identify the underlying concept before adopting the label. + +## P10. Test Concepts Against Scenarios + +Every canonical concept should survive concrete scenarios: enterprise +directories, vendor/customer tenancy, families, communities, social graphs, +service accounts, delegated agents, weak matches, strong links, and +pseudonymous profiles. + +## P11. Keep Implementation Recommendations Downstream + +The repository may recommend downstream schemas, APIs, UI flows, or adapters, +but it should not implement them directly. Implementation ideas belong in +`DownstreamRecommendations.md` or a dedicated downstream workplan. diff --git a/model/ConceptualModel.md b/model/ConceptualModel.md new file mode 100644 index 0000000..a186c4c --- /dev/null +++ b/model/ConceptualModel.md @@ -0,0 +1,144 @@ +# Conceptual Model + +Status: draft. This is the first narrative model extracted from the research +proposal. It is intentionally implementation-neutral and should be refined by +source-note backfill and scenario testing. + +## Core Claim + +Identity-canon should model identity-related systems as scoped actors, +records, identifiers, claims, credentials, relationships, and projections. The +model should keep social, legal, operational, authentication, and authorization +meanings visible instead of collapsing them into `user`, `group`, or `tenant`. + +## Entity Families + +### Actor Layer + +- Actor: participation root. +- Natural Person: human actor. +- Artificial Agent: non-human automated actor. +- Collective Actor: actor composed of, representing, or organizing multiple + actors. +- Organization, Community, Family or Household, Group, and Team: candidate + collective actor specializations. + +### Record Layer + +- Account: operational access record in a scope. +- Service Account: software-oriented account. +- Identity Record: source-specific record about an actor or account. +- Profile: presentation or attribute surface. +- Persona: contextual presentation of an actor. + +### Reference Layer + +- Identifier: value or reference within a scope. +- Scoped Identifier: identifier designed for limited correlation. +- Credential: proof or control material. +- Claim: statement made by a source or issuer. +- Evidence Source: support for claims, relationships, and synonymity. + +### Scope Layer + +- Scope: boundary for meaning. +- Tenant: administrative or isolation scope. +- Realm: issuer or security namespace. +- Namespace: naming scope. +- Authorization Domain: scope in which principals, resources, actions, and + policies are evaluated. + +### Projection Layer + +- Authenticated Subject: protocol projection of an identified entity. +- Authorization Principal: decision-engine projection of an actor, account, or + subject. +- Authorization Resource, Action, Policy, and Relationship Tuple: downstream + authorization projections, not canonical identity roots. + +## Relationship Classes + +Relationships should be explicit model elements when they affect meaning, +authorization, privacy, or lifecycle. + +Core relationship classes: + +- Membership: actor participates in a collective actor or scope. +- Affiliation: actor is associated with another actor or collective. +- Following: actor subscribes to or follows another actor or profile. +- Ownership: actor controls or is responsible for a record, resource, tenant, + or organization. +- Representation: actor acts on behalf of another actor. +- Delegation: actor grants bounded authority to another actor. +- Administration: actor manages records, relationships, or configuration in a + scope. +- Trust: actor, issuer, verifier, or system relies on another for a purpose. +- Synonymity: records or identifiers are asserted to refer to the same target + under stated evidence and scope. + +Recommended relationship fields: + +- relationship type; +- source and target; +- scope; +- source system or issuer; +- evidence reference; +- confidence or assurance when relevant; +- lifecycle state; +- privacy constraints; +- authorization implication, if any. + +## Identity Linking Model + +Identity linking should not merge records by default. It should create +Synonymity Assertions. + +Weak synonymity examples: + +- imported records match on name and email hash; +- two profiles share a phone number but lack explicit verification; +- an entity-resolution job proposes a duplicate. + +Strong synonymity examples: + +- account holder completes explicit account-linking flow; +- issuer signs a claim binding an identifier to a subject; +- operator verifies a link against authoritative evidence. + +Privacy-limited synonymity examples: + +- pairwise subject identifier bound only for one relying party; +- pseudonymous community profile linked only inside a restricted scope; +- legal identity reference stored separately from a public persona. + +## Invariants + +- A Natural Person can control zero, one, or many Accounts. +- An Account belongs to exactly one primary operational Scope, but can have + relationships to other scopes. +- A Profile presents an Actor, Account, or Persona within a Scope. +- A Principal is a projection for authorization and should not replace Actor or + Account in the canon. +- A Tenant can be related to an Organization or Customer, but should not be + treated as identical to either. +- A Group can carry Membership relationships, but Role assignment and + relationship semantics must stay explicit. +- A Synonymity Assertion can link records without destroying source identity or + evidence. +- Lifecycle state applies to relationships and assertions, not only accounts. + +## External Mapping Rule + +When mapping an external system, first identify which canonical layer the +source term belongs to: + +1. Actor layer: who or what participates? +2. Record layer: what operational record exists? +3. Reference layer: what values, claims, or credentials refer or prove? +4. Scope layer: where is the meaning valid? +5. Relationship layer: what typed connection is asserted? +6. Projection layer: what downstream protocol or authorization view is needed? + +Only after that mapping should source-specific labels such as `user`, `group`, +`organization`, `realm`, `tenant`, `subject`, or `principal` be adopted in a +downstream artifact. diff --git a/research/CorpusIndex.md b/research/CorpusIndex.md index 6882fa1..c5b063e 100644 --- a/research/CorpusIndex.md +++ b/research/CorpusIndex.md @@ -64,3 +64,20 @@ Each source note should capture: - usefulness for identity-canon; - candidate canonical mappings; - open questions. + +## Derived Canon Artifacts + +The first proposal follow-up pass created these draft artifacts from the +proposal and seeded corpus topics: + +- `terminology/TerminologyInventory.md` +- `terminology/TerminologyConflictMap.md` +- `canon/DesignPrinciples.md` +- `canon/CanonicalGlossary.md` +- `model/ConceptualModel.md` +- `scenarios/ScenarioTests.md` +- `OpenQuestions.md` +- `DownstreamRecommendations.md` + +These files are candidate canon surfaces. Treat them as hypotheses to test +while backfilling the individual source notes. diff --git a/scenarios/ScenarioTests.md b/scenarios/ScenarioTests.md new file mode 100644 index 0000000..00fd1a8 --- /dev/null +++ b/scenarios/ScenarioTests.md @@ -0,0 +1,189 @@ +# Scenario Tests + +Status: draft. These are narrative tests for the conceptual model. They are +not executable tests yet; they define expected representation checks for future +model revisions. + +## Test Format + +- Scenario: concrete identity situation. +- Expected representation: the canonical concepts that should be used. +- Checks: conditions the model must satisfy without collapsing terms. + +## S01. Single Person With One Local Account + +Expected representation: one Natural Person, one Account in an application +Scope, one local Identifier, one Profile, and one Membership or access +relationship if the account belongs to a group. + +Checks: + +- The person is not identical to the account. +- The profile is not the credential. +- Authorization can project the account or subject into a Principal. + +## S02. Person With Multiple Accounts Across Scopes + +Expected representation: one Natural Person, multiple Accounts, one Account +per Scope, and optional Synonymity Assertions linking account records. + +Checks: + +- Each account keeps its source and lifecycle state. +- Linking accounts does not merge them destructively. +- Different scopes can use different identifiers. + +## S03. Enterprise With Sub-Organizations + +Expected representation: Organization actors linked by structural +relationships, plus Accounts and Membership relationships scoped to relevant +systems. + +Checks: + +- Sub-organization is not automatically a tenant. +- Legal entity status is modeled separately. +- Membership and administration relationships are explicit. + +## S04. Vendor Tenant Serving Customer Tenants + +Expected representation: Vendor and Customer relationship roles between +Organization actors; Tenant scopes for platform isolation; optional +Administration relationships for delegated support. + +Checks: + +- Customer is not collapsed into Tenant. +- Vendor is not collapsed into Realm. +- Cross-tenant administration is scoped and evidenced. + +## S05. Customer Organization With Delegated Administrators + +Expected representation: Organization actor, Tenant scope, administrator +Accounts, Delegation and Administration relationships. + +Checks: + +- Admin rights are relationships, not just group names. +- Delegation has source, target, scope, and lifecycle state. +- Authorization projection can consume the relationship separately. + +## S06. Family With Guardian And Dependent Accounts + +Expected representation: Family or Household collective actor, Natural Person +actors, guardian/dependent relationships, child Accounts, and privacy +constraints. + +Checks: + +- Guardian relationship is not generic membership. +- Household and legal family can differ. +- Privacy-sensitive links can be scoped. + +## S07. Spontaneous Interest Group + +Expected representation: Community or Group collective actor, Membership +relationships, optional moderator Administration relationships. + +Checks: + +- Informal group does not need legal entity or tenant semantics. +- Moderation is not the same as membership. +- Group identity can exist without strong real-world identity proofing. + +## S08. Community With Members, Moderators, And Followers + +Expected representation: Community actor; Membership relationships for +members; Administration or moderation relationships for moderators; Following +relationships for followers. + +Checks: + +- Follower is not a member unless the source says so. +- Moderator authority is explicit and scoped. +- Public profile can differ from account. + +## S09. Social Media Follower Graph + +Expected representation: Actor or Persona profiles connected by Following +relationships in a social Scope. + +Checks: + +- Following is directed. +- Following does not imply affiliation, membership, trust, or authorization. +- Pseudonymous profiles can remain scoped. + +## S10. Bot Or Service Account Acting For An Organization + +Expected representation: Artificial Agent actor, Service Account, Organization +actor, Representation or Delegation relationship, and Credential records. + +Checks: + +- Bot is not a natural person. +- Service account has an owner or responsible actor. +- Delegated authority has bounded scope and lifecycle. + +## S11. AI Agent Acting Under Delegated Authority + +Expected representation: Artificial Agent actor, Account or Service Account, +Delegation relationship from a Natural Person or Organization, and audit or +evidence references for actions. + +Checks: + +- Delegation identifies who granted authority. +- Agent actions can be attributed without treating the agent as the person. +- Authorization projection can include delegated context. + +## S12. Weak Identity Match From Imported Data + +Expected representation: source Identity Records linked by a weak Synonymity +Assertion with method, evidence, confidence, scope, and lifecycle state. + +Checks: + +- Weak match does not merge accounts. +- Consumers can reject or quarantine weak links. +- Evidence source remains visible. + +## S13. Strong Account Link After Explicit Verification + +Expected representation: Accounts linked by a strong Synonymity Assertion or +Account Link relationship, with verification evidence and revocation path. + +Checks: + +- Strong link is still scoped. +- Verification method is recorded. +- Revocation or unlinking is possible. + +## S14. Pseudonymous Profile Linked Only Within A Restricted Scope + +Expected representation: Persona or Profile with Scoped Identifier and +privacy-limited Synonymity Assertion visible only inside an allowed Scope. + +Checks: + +- Public consumers cannot infer the hidden link. +- The pseudonym can have relationships independent of legal identity. +- Scope boundaries are explicit. + +## S15. Organization Represented By A Legal Entity And Operational Tenants + +Expected representation: Organization actor, Legal Entity specialization or +relationship, one or more Tenant scopes, and Representation relationships for +authorized persons or agents. + +Checks: + +- Legal entity and tenant are separate model elements. +- Multiple tenants can relate to one organization. +- Representation authority is scoped and evidenced. + +## Current Result + +The initial model can represent all fifteen scenarios at a narrative level. +The next research pass should backfill concrete mappings from source notes and +then revise the glossary where scenario checks reveal ambiguity. diff --git a/terminology/TerminologyConflictMap.md b/terminology/TerminologyConflictMap.md new file mode 100644 index 0000000..a23c70e --- /dev/null +++ b/terminology/TerminologyConflictMap.md @@ -0,0 +1,152 @@ +# Terminology Conflict Map + +Status: draft. This map records high-risk terms whose meanings differ across +source families. It should be revised after each source-note backfill. + +## Conflict: User + +Problem: `user` can mean a person, account, login credential holder, +application profile, authorization subject, or product-facing actor. + +Canonical stance: do not use `user` as a root concept. Require the writer to +choose among Natural Person, Account, Actor, Authenticated Subject, Principal, +Profile, or Persona. + +Current mapping rule: + +- If the system stores login state, map to Account. +- If the system renders a public or local display surface, map to Profile. +- If the system evaluates access, map to Principal or Authenticated Subject. +- If the text means a human being, map to Natural Person. + +## Conflict: Identity + +Problem: `identity` can mean selfhood, a directory record, an issuer-bound +subject, a set of claims, a DID, a credential, a profile, or an account. + +Canonical stance: avoid bare `identity`. Prefer Identity Record, Identifier, +Claim, Credential, Profile, Persona, or Synonymity Assertion. + +Current mapping rule: + +- A persistent record about an actor maps to Identity Record. +- A value used to refer maps to Identifier. +- A statement made by an issuer maps to Claim. +- Proof material maps to Credential. + +## Conflict: Account + +Problem: account can mean login account, customer billing account, social +account, service account, or account profile. + +Canonical stance: Account is an operational access record in a scope. Billing +or customer accounts need explicit relationship and commercial-role modeling. + +Current mapping rule: + +- Login-capable operational record maps to Account. +- Non-human login-capable record maps to Service Account. +- Commercial customer record maps to Customer relationship or Customer Account + only if a later source analysis justifies the separate concept. + +## Conflict: Subject, Principal, Actor + +Problem: protocols, authorization engines, and application models use these +terms differently. OIDC and SAML focus on subject identifiers; Cedar and IAM +often decide over principals; social and conceptual models talk about actors. + +Canonical stance: + +- Actor is the conceptual participant. +- Authenticated Subject is the issuer/protocol view after identification. +- Authorization Principal is the decision-engine projection. + +The same natural person or account may appear as all three in different +contexts, but the concepts should not be merged. + +## Conflict: Tenant, Realm, Organization, Customer + +Problem: multi-tenant products often use tenant, organization, realm, customer, +workspace, project, and account as partial synonyms. Some are isolation +boundaries, some are legal or commercial actors, and some are administrative +containers. + +Canonical stance: + +- Tenant is an administrative or isolation scope. +- Realm is an issuer or administrative namespace unless source analysis proves + stronger tenant semantics. +- Organization is a collective actor or organizational structure. +- Customer is a commercial relationship role. + +Model the relationships among these concepts instead of choosing one term to +stand for all of them. + +## Conflict: Group, Role, Team, Community + +Problem: IAM systems often use groups for role assignment, collaboration tools +use teams for work coordination, and social platforms use groups or communities +for participation. + +Canonical stance: + +- Group is a named collection or collective actor with membership. +- Role is a capability bundle or relationship label. +- Team is a domain-specific group or organization unit. +- Community is a participation-oriented collective actor. + +Avoid modeling all four as generic `group`. + +## Conflict: Member, Follower, Affiliate + +Problem: membership, following, affiliation, employment, subscription, and +moderation relationships are often hidden behind `member`. + +Canonical stance: relationship type matters. Represent each relationship with +source, target, scope, role or relation kind, evidence, lifecycle state, and +authorization implications if any. + +## Conflict: Profile And Persona + +Problem: profiles are sometimes account records, public pages, social +identities, or collections of claims. Personas are sometimes aliases, +pseudonyms, or UX-specific presentations. + +Canonical stance: + +- Profile is a presentation or attribute surface in a scope. +- Persona is a deliberate contextual presentation of an actor, often separate + from other presentations for privacy or role clarity. + +## Conflict: Identifier, Credential, Claim + +Problem: identifiers, credentials, and claims are often conflated because all +can appear in tokens, profiles, or identity documents. + +Canonical stance: + +- Identifier refers. +- Credential proves or supports. +- Claim states. + +A token may contain all three, but the conceptual model should keep them apart. + +## Conflict: Synonymity, Linking, Matching, Merge + +Problem: identity systems often collapse weak matches, verified account links, +same-as claims, and destructive record merges into a single identity-linking +feature. + +Canonical stance: synonymity is an assertion. It has source, target, scope, +confidence, evidence, method, lifecycle state, and privacy constraints. It does +not require destructive merging. + +## Review Queue + +- Validate each conflict against populated source notes. +- Add concrete examples and counterexamples once source summaries include + citations. +- Decide whether Customer Account deserves a canonical concept or stays a + downstream commercial model. +- Decide whether Realm should remain a Scope specialization or become a + separate canonical concept. diff --git a/terminology/TerminologyInventory.md b/terminology/TerminologyInventory.md new file mode 100644 index 0000000..ed7152f --- /dev/null +++ b/terminology/TerminologyInventory.md @@ -0,0 +1,72 @@ +# Terminology Inventory + +Status: draft. This inventory is seeded from `ResearchProposal.md`, +`INTENT.md`, and the current research corpus index. Mappings are candidate +canonical mappings until the individual source notes have been backfilled with +real source summaries. + +## Use + +Use this file to collect source terms and their current candidate canonical +home. Use `terminology/TerminologyConflictMap.md` when a term is overloaded or +has incompatible meanings across source families. + +## Inventory + +| Term | Candidate canonical concept | Source families | Notes | +| --- | --- | --- | --- | +| actor | Actor | authorization, social graphs, proposal | Participation root for anything that can act or be acted for. | +| natural person | Natural Person | identity assurance, social graphs | Human being; never identical to an account or profile. | +| user | Convenience label only | SCIM, products, applications | Overloaded; map to Account, Actor, Subject, or Profile by context. | +| account | Account | SCIM, LDAP, IAM products | Operational record that enables access in a scope. | +| identity | Identity Record or Identity Claim | IAM, federation, DID, VC | Avoid as root noun; clarify whether record, claim, identifier, or social identity is meant. | +| identifier | Identifier | OIDC, SAML, DID, directories | A value or reference used to distinguish something in a scope. | +| credential | Credential | authentication, VC, DID | Evidence or secret material used to prove control, entitlement, or claim. | +| subject | Authenticated Subject | OIDC, SAML, authorization | Security-protocol view of an actor/account after identification by an issuer. | +| principal | Authorization Principal | Cedar, IAM, authorization | Entity considered by an authorization decision. | +| profile | Profile | social graphs, IAM, applications | Presentation or attribute surface for an actor/account in a scope. | +| persona | Persona | social/community systems | Deliberate contextual presentation of an actor, often with limited linkage. | +| agent | Artificial Agent | IAM, agentic systems | Non-human actor, including bot, service account, or AI agent. | +| bot | Artificial Agent | applications, social graphs | Automated actor; may act through an account and under delegation. | +| service account | Service Account | IAM, operations | Account intended for software or workload access rather than human login. | +| organization | Organization | SCIM, LDAP, Keycloak, ZITADEL | Collective actor or structure; do not collapse with tenant, legal entity, or customer. | +| legal entity | Legal Entity | business, compliance | Organization recognized under a legal system. | +| customer | Customer | SaaS, vendor/customer models | Commercial relationship role, not automatically a tenant or organization. | +| vendor | Vendor | SaaS, multi-vendor systems | Provider role in a commercial or operational relationship. | +| tenant | Tenant | SaaS, IAM products | Administrative or isolation scope; may be owned by or assigned to an organization. | +| realm | Realm | Keycloak, federation | Issuer or administrative namespace; candidate mapping is Scope or Tenant depending on use. | +| scope | Scope | OIDC, authorization, proposal | Boundary in which identifiers, policies, relationships, or meanings hold. | +| namespace | Scope | directories, DID, products | Naming boundary; treat as a kind of scope unless stronger semantics exist. | +| community | Community | social graphs, platforms | Collective actor defined by social participation rather than legal or customer status. | +| family | Family or Household | family account models | Relationship network with guardian/dependent semantics and privacy sensitivity. | +| household | Family or Household | family account models | Co-residence or account-management unit; may not equal legal family. | +| group | Group | LDAP, SCIM, social graphs, authz | Container or collective label; must not absorb relationship semantics. | +| team | Group or Organization Unit | SaaS, collaboration systems | Usually a collaboration group; sometimes an org sub-unit. | +| role | Role | RBAC, IAM products | Named capability set or relationship label; keep separate from group membership. | +| member | Membership Relationship | SCIM, groups, communities | Relationship from actor to collective actor or scope. | +| affiliation | Affiliation Relationship | enterprise, social | Looser association than membership; may be external or evidenced. | +| follower | Following Relationship | ActivityPub, social graphs | Directed social relationship, not a membership or authorization grant by default. | +| owner | Ownership Relationship | SaaS, authz | Control or responsibility relationship; needs scope and target. | +| administrator | Administration Relationship | IAM, SaaS | Delegated management authority in a scope. | +| delegation | Delegation Relationship | IAM, authz, agentic systems | Actor grants another actor authority to act in a bounded way. | +| representation | Representation Relationship | legal, org, agent systems | Actor acts on behalf of another actor or organization. | +| trust | Trust Relationship | federation, DID, authz | Reliance relationship; must record source, scope, and purpose. | +| claim | Claim | VC, OIDC, DID | Statement made by an issuer about a subject, actor, or relationship. | +| evidence | Evidence Source | entity resolution, assurance | Material supporting a claim or synonymity assertion. | +| assurance | Assurance Level | NIST, federation | Confidence about identity proofing, authentication, or binding. | +| identifier binding | Identifier Binding | federation, entity resolution | Assertion that an identifier refers to a target within a scope. | +| synonymity | Synonymity Assertion | entity resolution, proposal | Assertion that two records or identifiers refer to the same target under stated conditions. | +| weak match | Weak Synonymity Assertion | entity resolution | Probabilistic or low-confidence link; never a destructive merge. | +| strong link | Strong Synonymity Assertion | account linking, identity proofing | Verified or authoritative link; still scoped and evidenced. | +| pseudonym | Pseudonymous Identifier | privacy, OIDC, DID | Identifier designed to limit cross-scope correlation. | +| pairwise subject | Scoped Identifier | OIDC | Subject identifier scoped to relying party or sector; map to Identifier plus Scope. | +| relationship tuple | Relationship Assertion | Zanzibar, OpenFGA | Authorization-oriented representation of actor-object-relation facts. | +| policy | Authorization Projection | Cedar, IAM, authz | Rule artifact; not part of the canonical identity object model except as mapping. | +| lifecycle state | Lifecycle State | SCIM, IAM, directories | Activation, suspension, deletion, revocation, or archival state of a record or relationship. | + +## Backfill Needs + +- Add source-specific definitions from each file in `research/*/*.md`. +- Split terms that hide multiple meanings after source review. +- Add citation pointers once source notes contain stable references. +- Move mature canonical definitions to `canon/CanonicalGlossary.md`. diff --git a/workplans/IDENTITY-WP-0001-statehub-bootstrap.md b/workplans/IDENTITY-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..5aa8934 --- /dev/null +++ b/workplans/IDENTITY-WP-0001-statehub-bootstrap.md @@ -0,0 +1,71 @@ +--- +id: IDENTITY-WP-0001 +type: workplan +title: "Bootstrap State Hub integration" +domain: canon +repo: identity-canon +status: finished +owner: codex +topic_slug: canon +created: "2026-06-05" +updated: "2026-06-05" +state_hub_workstream_id: "b7346171-35f6-45bf-b82f-c3703b79b426" +--- + +# Bootstrap State Hub integration + +Orthogonal vocabulary and canonical model for identity-related concepts. + +## Review Generated Integration Files + +```task +id: IDENTITY-WP-0001-T01 +status: done +priority: high +state_hub_task_id: "3d373474-4258-40f0-9d44-7e26f7ccfc69" +``` + +Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. +Replace generated placeholders with repo-specific facts where needed. + +Completed by reviewing the generated integration files, preserving +`.custodian-brief.md` as generated output, refining `SCOPE.md` to the actual +research-only repository boundary, and correcting `AGENTS.md` repo identity. + +## Verify Local Developer Workflow + +```task +id: IDENTITY-WP-0001-T02 +status: done +priority: high +state_hub_task_id: "c465b751-5799-47a2-b1e0-93017b39b9a7" +``` + +Identify the repo's install, test, lint, build, and run commands. Add or refine +those commands in the agent instructions so future coding sessions can verify +changes confidently. + +Completed by adding the local developer workflow to `AGENTS.md`. The repository +is documentation-only: no install, build, runtime service, package manifest, or +configured test runner exists. Current verification is `rg --files`, `git diff +--check`, and State Hub ADR-001 consistency sync after workplan changes. + +## Seed First Real Workplan + +```task +id: IDENTITY-WP-0001-T03 +status: done +priority: medium +state_hub_task_id: "2baf0a58-ad4e-4888-a02a-0935bd329c43" +``` + +Create the first implementation workplan for the repository's most important +next change. After workplan file updates, run from `~/state-hub`: + +```bash +make fix-consistency REPO=identity-canon +``` + +Completed by `IDENTITY-WP-0002`, which follows up on `ResearchProposal.md` by +seeding the first terminology, canon, model, scenario, open-question, and +downstream recommendation artifacts. diff --git a/workplans/IDENTITY-WP-0002-research-proposal-follow-up.md b/workplans/IDENTITY-WP-0002-research-proposal-follow-up.md new file mode 100644 index 0000000..6e7ce24 --- /dev/null +++ b/workplans/IDENTITY-WP-0002-research-proposal-follow-up.md @@ -0,0 +1,86 @@ +--- +id: IDENTITY-WP-0002 +type: workplan +title: "Research proposal follow-up: initial canon scaffold" +domain: canon +repo: identity-canon +status: finished +owner: codex +topic_slug: canon +created: "2026-06-05" +updated: "2026-06-05" +state_hub_workstream_id: "ddb6ca2b-2b35-4dd7-a1fb-f31a51de44f5" +--- + +# Research proposal follow-up: initial canon scaffold + +This workplan follows up on `ResearchProposal.md`, especially Immediate Next +Steps 5 through 9. The goal is to turn the seeded proposal and corpus outline +into the first repository-native terminology, canon, model, and scenario +artifacts without pretending that the source-note research pass is complete. + +## Seed Terminology Inventory + +```task +id: IDENTITY-WP-0002-T01 +status: done +priority: high +state_hub_task_id: "2c66f05d-a19f-4f29-a24d-8cb43c0e7da1" +``` + +Create the first `terminology/TerminologyInventory.md` from the proposal, +intent, and seeded corpus topics. The inventory must mark mappings as +candidate mappings until the individual source notes are backfilled. + +## Seed Terminology Conflict Map + +```task +id: IDENTITY-WP-0002-T02 +status: done +priority: high +state_hub_task_id: "eeca8178-76ec-485c-bace-70ed13d4a418" +``` + +Create the first `terminology/TerminologyConflictMap.md` for overloaded terms +that are central to the proposal: `user`, `identity`, `account`, `subject`, +`principal`, `tenant`, `organization`, `group`, `role`, `member`, `profile`, +`persona`, `identifier`, `credential`, and synonymity terms. + +## Draft Canonical Principles And Glossary + +```task +id: IDENTITY-WP-0002-T03 +status: done +priority: high +state_hub_task_id: "44fb593e-1118-412f-a3d8-3976958ad175" +``` + +Create `canon/DesignPrinciples.md` and `canon/CanonicalGlossary.md` as the +first explicit canonical layer. These files should stay implementation-neutral +and keep external product mappings separate from canonical definitions. + +## Add Model And Scenario Tests + +```task +id: IDENTITY-WP-0002-T04 +status: done +priority: medium +state_hub_task_id: "9a922e09-0609-4dcb-9828-00d12009c9eb" +``` + +Create `model/ConceptualModel.md` and `scenarios/ScenarioTests.md` so the +initial canon can be tested against the representative scenarios listed in the +research proposal. + +## Record Follow-Up Boundaries + +```task +id: IDENTITY-WP-0002-T05 +status: done +priority: medium +state_hub_task_id: "3231c998-2e1a-4d35-a9c2-c7ff6888394f" +``` + +Create lightweight follow-up surfaces for open questions and downstream +recommendations. These notes should keep implementation ideas visible without +moving implementation work into this repository.