# Share and manage permissions

**Flow key:** `share-and-permissions`

## Outcome

An authorized owner grants the intended person exactly the intended access, and changes or revocation propagate to every entry point.

## Actors

- Owner/admin
- Recipient/collaborator
- Permission service
- Notification provider

## Preconditions and entry points

- A synthetic resource and tenant exist.
- Roles, link-sharing, inheritance, guest, and revocation policies are known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Resource | `CARBON-DOC-001` | folder/project, sensitive, archived, inherited child |
| Recipient | `carbon.share+001@example.test` | existing member, guest, group, wrong tenant, disabled |
| Permission | viewer | commenter, editor, owner/admin, custom, expired |
| Link | restricted named-recipient link | anyone link, password/expiry, forwarded, indexed |
| State | unshared resource | already shared, conflicting inherited permission, recipient removed |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Open sharing for the exact resource. | Current direct, inherited, link, and public access are visible. |
| 2 | Choose recipient and least-privilege role. | Identity is unambiguous and prohibited escalation is unavailable. |
| 3 | Review and confirm. | Scope, notification, expiry, and downstream access are explicit. |
| 4 | Recipient follows notification/link. | Authentication and tenant binding lead only to the intended resource and actions. |
| 5 | Change role and revoke access. | Open sessions, links, caches, downloads, search, and API access converge under policy. |
| 6 | Inspect audit and affected descendants/integrations. | Actor, target, old/new access, inheritance, and notification are accurate. |

## Alternate paths

- Named sharing
- Public/anyone link
- Organization/group sharing
- Inherited folder/project access
- Temporary guest access

## Failure and recovery paths

- Recipient ambiguity
- Permission changes between render and commit
- Forwarded link
- Revocation lags caches
- Notification succeeds but permission write fails

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [permission](../../items/automation/permission.md)
- [team membership role owner assignment](../../items/identity/team-membership-role-owner-assignment.md)
- [email and outbound message](../../items/content/email-and-outbound-message.md)
- [privacy](../../items/quality/privacy.md)

[Back to Productivity and collaboration flows](index.md)
