diff --git a/bitwarden_license/bit-web/src/app/pam/CLAUDE.md b/bitwarden_license/bit-web/src/app/pam/CLAUDE.md index 680d9562f6a..4f6e8baa0e8 100644 --- a/bitwarden_license/bit-web/src/app/pam/CLAUDE.md +++ b/bitwarden_license/bit-web/src/app/pam/CLAUDE.md @@ -6,28 +6,29 @@ requester's leasing flow, and the approver's inbox. Gated behind `FeatureFlag.Pa ## Surfaces -- `abstractions/` / `helpers/` / `date/` — framework-agnostic contract layer: domain - types and error helpers (`abstractions/access-rule.ts`, `abstractions/access-lease.ts`), - the abstract service contracts, and pure helpers. Re-exported via `index.ts`. No +- `bit-pam/src/` (`abstractions/`, `helpers/`, `date/`, `services/`), the framework-agnostic + contract layer: domain types and error helpers (`abstractions/access-rule.ts`, + `abstractions/access-lease.ts`), the abstract service contracts, pure helpers, and the SDK-backed + services. Re-exported via `bit-pam/src/index.ts`. No Angular runtime APIs here; keep it that way so this stays unit-testable without a TestBed. Type-only imports of component-library option shapes (e.g. `SimpleDialogOptions`) are fine, since they are erased at compile time. -- `access-rules/` — list (`access-rules.component` + `.service`) and the routed - create/edit page (`access-rule-edit.component`), at `access-rules`, - `access-rules/new`, `access-rules/:accessRuleId`. -- `access-rules/access-rule-edit/ip-allowlist/` — the `ip_allowlist` condition's CIDR +- `access-rules/`, list (`access-rules.component`, with `services/access-rules.service.ts`) and the + routed create/edit page (`access-rule-edit.component`), at `access-rules`, `access-rules/new`, + `access-rules/:accessRuleId`. +- `access-rules/access-rule-edit/ip-allowlist/`, the `ip_allowlist` condition's CIDR editor plus its validators (delegates to the SDK's `is_valid_cidr`). The editor is a thin view over a `FormArray` owned by the edit page's form group (passed in via a `cidrArray` input): the array-level validators live on the host control so validity flows through the parent form, and the page disables the array while the condition is off. Per-row CIDR validation rides on each pushed control. -- `access-requests/` — the user-scoped "Access requests" page at `/pam`: a tabbed shell +- `access-requests/`, the user-scoped "Access requests" page at `/pam`: a tabbed shell (`access-requests.component`) over Approvals, My requests, and History, plus the shareable single request at `/pam/requests/:id`. `MyAccessService`, `ApproverInboxService`, and `AccessNameResolverService` are provided on the SHELL ROUTE, not on the component, because routed children inherit a parent route's - providers but not a component's — that is what lets the tabs share one load. -- `access-requests/access-request-route/` — `/pam/requests/:id`. A real route, not a + providers but not a component's. That is what lets the tabs share one load. +- `access-requests/access-request-route/`, `/pam/requests/:id`. A real route, not a click handler, because the rows link to it and both the requester's and the approvers' emails deep-link to it; but a DIALOG over the shell rather than a page of its own. It is a fourth child of the shell route, so the header and tab bar stay mounted; @@ -51,54 +52,62 @@ requester's leasing flow, and the approver's inbox. Gated behind `FeatureFlag.Pa router's `previousNavigation` says only that this SPA session navigated before, never that the browser has an entry below this one to go back to. `AccessRequestDetailService` is provided on the host component, not the route config, - because it reads the `:id` off `ActivatedRoute` — a route-level provider resolves in + because it reads the `:id` off `ActivatedRoute`: a route-level provider resolves in the route's environment injector, where that lookup falls through to the root route. The host hands the service to the dialog through `DIALOG_DATA` for the same reason: `DialogService` builds the dialog's injector from the root one. -- `approvals/` — the approver side: the SDK-backed inbox data service, the decide +- `approvals/`, the approver side: the SDK-backed inbox data service, the decide dialog, the privilege check, and the route guard. -- `request-summary/` — the item and "Request details" cards shared by the decide dialog +- `request-summary/`, the item and "Request details" cards shared by the decide dialog and the `/pam/requests/:id` dialog. -- `access-audit/` — the Admin Console's PAM audit log at `audit`: the page, the event +- `access-audit/`, the Admin Console's PAM audit log at `audit`: the page, the event drawer, and export. It reads over HTTP through `AuditApiService` (see "SDK-first"). -- `rotation/` — the Admin Console's rotation pages at `rotation` (access connectors and +- `rotation/`, the Admin Console's rotation pages at `rotation` (access connectors and managed credentials), lazy-loaded from `rotation.routes.ts` behind `FeatureFlag.PamAccessConnector`. -- `cipher-view-banner/` — the requester's entry point on an open gated cipher: five - states, four off `cipher_access_state()` plus an inline request form, and the licensing - block (PM-39423). The block comes FIRST and replaces every other state, active lease - included, because the server stops releasing a gated cipher's secrets to an unlicensed - holder whatever lease they hold (`CipherLeaseGate.LeaseCanRelease`) — withdrawing a seat - withdraws what the outstanding leases were carrying, so a countdown here would narrate - access no longer being served. Withdrawing an outstanding request stays reachable from the - vault-row menu and the My requests tab, neither of which is licensing-gated. It is also the - one state not derived from the access-state read: licensing is per-member, so it comes off - local membership state via `services/pam-membership.ts` with no round trip, and renders even - when that read fails. The signal is tri-state — `undefined` until membership lands — so - readers test `=== false`, not truthiness; treating "not yet known" as licensed flashes the - request card and fires its pre-check at someone about to be blocked. -- `services/pam-membership.ts` — `callerOrganizations$` (the `getOptionalUserId` + +- `cipher-view-banner/`, the requester's entry point on an open gated cipher (it lives in + `bit-pam-components`, with each state's card under `cards/`, the form in `request-access-form/`, + the popup's sheet around it in `request-access-sheet/`, and the human path's window picker in + `request-window-fields/`): seven states, six off `cipher_access_state()` (including Unavailable, + when the rule refuses a request right now, and Access ended) and the licensing block (PM-39423). + The Request access card, and the Access ended card when a new request is possible, hold the + Request access button, which folds the request form out in the item view, or opens it in a bottom + sheet where `CIPHER_VIEW_BANNER_LAYOUT` says `popup` (the extension, which also puts the actions + above the cards). The licensing block comes FIRST and replaces every other state, active lease + included, because the server stops releasing a gated cipher's secrets to an unlicensed holder + whatever lease they hold (`CipherLeaseGate.LeaseCanRelease`); withdrawing a seat withdraws what + the outstanding leases were carrying, so a countdown here would narrate access no longer being + served. Withdrawing an outstanding request stays reachable from the vault-row menu and the My + requests tab, neither of which is licensing-gated; the banner's approved card offers only Start + access, and only the pending card offers Cancel request. The active card drops Extend and End once + the lease is inside `ENDING_SOON_THRESHOLD_MS` (five minutes), as the design specifies. The + licensing block is also the one state not derived from the access-state read: licensing is + per-member, so it comes off local membership state via `bit-pam/src/services/pam-membership.ts` + with no round trip, and renders even when that read fails. The signal is tri-state, `undefined` + until membership lands, so readers test `=== false`, not truthiness; treating "not yet known" as + licensed flashes the request card and fires its pre-check at someone about to be blocked. +- `bit-pam/src/services/pam-membership.ts`, `callerOrganizations$` (the `getOptionalUserId` + `organizations$` pipeline several surfaces here hand-rolled) and `unlicensedForPam`. The latter is PRESENTATION policy, which is why it is not on `Organization`: only `Organization.canAccessPrivilegedAccess` (`usePam && accessPam`, shaped like `canAccessSecretsManager`) is the entitlement the server evaluates. The other three - conditions decide whether it is honest to say anything at all — no `usePam` (no license to + conditions decide whether it is honest to say anything at all: no `usePam` (no license to be missing), `accessPam !== false` (an un-synced persisted blob is not an answer), not `enabled` (a lapsed subscription is the wrong reason), and never a provider user (`ProfileProviderOrganizationResponseModel` hardcodes `AccessPam = false` while still reporting the client org's `UsePam`). Do not "simplify" it to `!accessPam`. -- `vault-filter-gated-collection/` — the lock glyph beside a governed collection in the +- `vault-filter-gated-collection/`, the lock glyph beside a governed collection in the vault's Filters sidebar. Reads the same server-derived `hasEnabledAccessRule` the collection-row badge does, off the sidebar's own collection node. `VaultFilterService.buildCollectionTree` rebuilds each node through - `new CollectionView(...)`, which resets that flag to `false` — so it is carried over + `new CollectionView(...)`, which resets that flag to `false`, so it is carried over onto the copy explicitly, rather than re-deriving "governed" from a `listAccessRules` read. That read required organization membership, which a provider browsing a client org's Admin Console does not have, so it used to fail closed to unmarked there; reading the flag instead works identically for members and providers, and in both the individual vault and the Admin Console org sidebar (the same `VaultFilterSectionComponent` hosts it in both). -- `gated-collection-banner/` — the notice above the vault's item list while a governed +- `gated-collection-banner/`, the notice above the vault's item list while a governed collection is the active filter, carrying the sidebar lock's sentence verbatim. It cannot read the flag the way the sidebar lock and the collection-row badge do, because it is handed ids alone, never a collection: it decides "governed" through @@ -106,22 +115,26 @@ requester's leasing flow, and the approver's inbox. Gated behind `FeatureFlag.Pa `rulesGoverningCollection` pair the collection dialog uses, and narrows to the collection's own PAM-enabled organization before reading at all. A new surface that is likewise handed no collection belongs on that helper, not on a re-derived check. -- `vault-filter-controlled-access/` — the "Controlled access" filter, in two option sets over - one narrowing. The legacy sidebar's children (`options$`, `CONTROLLED_ACCESS_FILTERS`) are - state groups: "Privileged" and "My requests" (`pending`/`ready`/`active`). The VFO1 vault - table's multi-select chip (`stateOptions$`, `CONTROLLED_ACCESS_STATE_FILTERS`) offers one +- `bit-pam-components/src/vault-filter-controlled-access/`, the vault tables' "Controlled access" + filter. The multi-select chip (`stateOptions$`, `CONTROLLED_ACCESS_STATE_FILTERS`) offers one option per `AccessBadgeState.kind`, labelled like the badge it admits, so its counts match - the badges on screen; the table ORs the selected options itself. "Unavailable" matches - nothing until the SDK produces that kind. Each row's state is read once per row list and - shared across options (`accessKinds$`), so the chip's counts don't multiply the reads. Add an - option by appending to the matching list, not by branching in `narrow$`. -- `access-state-badge/`, `vault-row-lease-badge/`, `item-details-state-badge/` — the one + the badges on screen; the table ORs the selected options itself. "Ending soon" splits the + active leases at `ENDING_SOON_THRESHOLD_MS`, so "In use" is the badge's "X left" and a lapsed + lease is in neither. "Unavailable" matches items whose rule refuses a request right now. Each + row's state is read once per row list and shared across options (`accessKinds$`), so the + chip's counts don't multiply the reads. Add an option by appending to the list, not by + branching in `matches$`. The service and the chip factory live in `bit-pam-components` + because the extension popup binds the same `VAULT_ITEM_FILTER` in `bit-browser`'s + `provide-pam.ts`, and `bit-browser` cannot import `bit-web`. +- `access-state-badge/`, `vault-row-lease-badge/`, `item-details-state-badge/`: the one access-state pill, and the two hosts that render it: a vault row, and the open item's - name row. Both re-read on `AccessRefreshService` so neither can contradict a mutation - made beside it — the row badge because canceling a request from that row's own menu + name row. The pill and the item-details host live in `bit-pam-components`, and the badge model + (`access-badge-state.ts`) in `bit-pam`; only `vault-row-lease-badge/` and the pill's stories are + here. Both hosts re-read on `AccessRefreshService` so neither can contradict a mutation + made beside it: the row badge because canceling a request from that row's own menu otherwise left the old pill standing until a reload (PAM-200). The item-details host also drops the `active` state, because the banner heading under it already runs that - countdown on its own timer — but it drops it on a LIVE lease (`liveActiveLease`), not on + countdown on its own timer, but it drops it on a LIVE lease (`liveActiveLease`), not on the SDK's `active` ranking, or a lease the server still believes in after it lapsed would hide the pill for good (see "A lease running out"). Which badge to show is NOT decided here: the SDK ranks the three states into `CipherAccessStateView.badgeState`, and @@ -129,15 +142,17 @@ requester's leasing flow, and the approver's inbox. Gated behind `FeatureFlag.Pa discriminant, a parsed `Date`). Add a state by teaching the SDK, not by re-ranking the parts client-side. `ENDING_SOON_THRESHOLD_MS` (`access-badge-state.ts`) is the five-minute cutoff at which an - active lease escalates to the danger recipe — a fixed cutoff, not a fraction of the lease's + active lease escalates to the danger recipe, a fixed cutoff, not a fraction of the lease's length (PM-40498). It is exported rather than private to the badge because the cipher-view banner escalates on it too: that surface has the `active` badge suppressed, so its heading is the only countdown there and has to carry the warning itself. A new countdown must read this constant, not restate five minutes. -- `collection-access-rule-callout/` — names the rules governing a collection, inside the - collection edit dialog. -- `services/` — the SDK-backed implementations of the `abstractions/` contracts. -- `testing/` — builders shared across specs (`decision-builders.ts`). +- `collection-access-rule-callout/`, the callout naming the rules that govern a collection, + inside the collection edit dialog. +- `services/`, this folder's own services, among them `AccessRulesService`, + `GovernedCollectionsService`, `PamRevealedCipherService` and the nav badge. The SDK-backed + implementations of the `abstractions/` contracts are in `bit-pam/src/services/`. +- `testing/`, builders shared across specs (`decision-builders.ts`). ## SDK-first @@ -145,49 +160,49 @@ Every PAM call goes through the Rust SDK (`client.commercial().pam()`), never HT exception left is `access-audit/`: `AuditApiService` reads the audit trail over HTTP because the SDK has no audit client yet (see `access-audit/README.md`). `AccessRuleSdkService`, `AccessRequestSdkService`, `AccessLeaseSdkService`, and -`ApprovalSdkService` are the abstract contracts; `services/*-sdk.service.ts` compose the -SDK client. `ApprovalSdkService` (`services/approvals-sdk.service.ts`) covers the -approver-facing surface — the pending inbox, the decided history, recording a -decision, and withdrawing an approval — via `commercial().pam().approvals()`. +`ApprovalSdkService` are the abstract contracts; `bit-pam/src/services/*-sdk.service.ts` compose the +SDK client. `ApprovalSdkService` (`bit-pam/src/services/approvals-sdk.service.ts`) covers the +approver-facing surface (the pending inbox, the decided history, recording a +decision, and withdrawing an approval) via `commercial().pam().approvals()`. -**If a PAM capability turns out to be missing from the SDK, that is SDK work — not a +**If a PAM capability turns out to be missing from the SDK, that is SDK work, not a raw-HTTP route.** An approver ending a lease and an approver withdrawing an approval go through the SDK (`leases().end()` and `approvals().revoke()`) for the same reason. ## Error shape -`abstractions/access-rule.ts` re-exports the SDK's `AccessRuleError` — a flat shape -(`{ name: "AccessRuleError", variant, message }`) following the wasm-bindgen error convention — -and pairs it with a LOCAL structural guard, because the SDK's own `isAccessRuleError` is a runtime -wasm import and this directory stays type-only (see "`export type` matters" below). Use +`bit-pam/src/abstractions/access-rule.ts` re-exports the SDK's `AccessRuleError`, a flat shape +(`{ name: "AccessRuleError", variant, message }`) following the wasm-bindgen error convention, and +pairs it with a LOCAL structural guard, because the SDK's own `isAccessRuleError` is a runtime wasm +import and `abstractions/` stays type-only (see "`export type` matters" below). Use `accessRuleErrorMessage()` / `isAccessRuleNotFound()` to interpret it; never treat it as -`ErrorResponse`. The SDK splits its own failures per client — -`AccessRequestError` (request/activate/cancel), `ApprovalError` (decide/revoke) and -`AccessLeaseError` (read/extend/end). `abstractions/access-lease.ts` unions them as `LeasingError`, detected -through the injectable `LeasingErrorService` seam so consumers never import the wasm guards. -All three carry an `Api` variant holding the server's message. That variant's payload is the whole -serialized response, so `abstractions/api-error.ts` owns the one `apiErrorBodyMessage()` decode of -the `ErrorResponseModel` body — use it rather than re-parsing; what a miss means (generic copy, or -the raw string) stays with the caller. +`ErrorResponse`. The SDK splits its own failures per client: `AccessRequestError` +(request/activate/cancel), `ApprovalError` (decide/revoke) and `AccessLeaseError` (read/extend/end). +`bit-pam/src/abstractions/access-lease.ts` unions them as `LeasingError`, detected through the +injectable `LeasingErrorService` seam so consumers never import the wasm guards. All three carry an +`Api` variant holding the server's message. That variant's payload is the whole serialized response, +so `bit-pam/src/abstractions/api-error.ts` owns the one `apiErrorBodyMessage()` decode of the +`ErrorResponseModel` body. Use it rather than re-parsing; what a miss means (generic copy, or the +raw string) stays with the caller. -`helpers/pam-license-error.ts` owns the one copy of the server's licensing refusal +`bit-pam/src/helpers/pam-license-error.ts` owns the one copy of the server's licensing refusal (`PamLicenseGuard.UnlicensedMessage`), which all three acquiring paths throw. The submit and activate catalogs and the extend handler all match through it rather than spelling the sentence -again — only its FIRST sentence, so the "ask your admin" half can be reworded server-side without -degrading three surfaces to generic copy. Note the two surfaces with no licensing block of their -own — the My requests tab and the shared request dialog — reach it only through that toast, since -they offer Start off a request row with no cipher in hand. +again. They match only its FIRST sentence, so the "ask your admin" half can be reworded server-side +without degrading three surfaces to generic copy. Note the two surfaces with no licensing block of +their own, the My requests tab and the shared request dialog, reach it only through that toast, +since they offer Start off a request row with no cipher in hand. -A rejected access-request submit is interpreted by -`helpers/request-access-error.ts`. Three of the server's messages mean the caller already -has what they asked for; those are reconciled (collapse the form, re-read the state) rather -than surfaced as errors. The licensing refusal, and the condition denials the automatic path -throws, show activation's localized strings (`refused`) rather than the server's English. +A rejected access-request submit is interpreted by `bit-pam/src/helpers/request-access-error.ts`. +Three of the server's messages mean the caller already has what they asked for; those are reconciled +(close the form, re-read the state) rather than surfaced as errors. The licensing refusal, and the +condition denials the automatic path throws, show activation's localized strings (`refused`) rather +than the server's English. That file carries TWO catalogs, and the split is deliberate. `REQUEST_ACCESS_SERVER_ERRORS` holds the sentences `SubmitAccessRequestCommand` throws; `REQUEST_ACCESS_SDK_ERRORS` holds the ones the SDK raises locally, before the wire, which reach `.message` verbatim because -`AccessRequestError::Validation` is `#[error(transparent)]`. The two are NOT kept in step — an +`AccessRequestError::Validation` is `#[error(transparent)]`. The two are NOT kept in step: an elapsed window is "The end date must be in the future." from the server and "The requested window has already ended." from the SDK. They were once assumed identical, so only the SDK's spelling was listed and every server-side refusal fell through to the generic toast @@ -195,7 +210,7 @@ spelling was listed and every server-side refusal fell through to the generic to sentences are pinned in `request-access-error.spec.ts` rather than compared against themselves, so drift fails a test instead of degrading the copy silently. -The two `*ExceedsMax` refusals are NOT catalog entries — the server interpolates its +The two `*ExceedsMax` refusals are NOT catalog entries: the server interpolates its `EffectiveMax` into them, so no fixed sentence matches more than one rule. `EXCEEDS_MAX_PATTERN` captures the noun and the maximum instead, and also matches the SDK's local window refusal, which has no full stop. The window path re-renders through @@ -204,14 +219,14 @@ Keep the noun: the automatic path shows no window, so the two cannot share wordi ## `export type` matters -`abstractions/access-rule.ts` and `abstractions/access-lease.ts` re-export SDK shapes -using `export type` (not `export`) — type-only and erased at compile time, so jest never -resolves the wasm SDK package when running this directory's unit tests. Keep new +`bit-pam/src/abstractions/access-rule.ts` and `access-lease.ts` re-export SDK shapes +using `export type` (not `export`), type-only and erased at compile time, so jest never +resolves the wasm SDK package when running `bit-pam`'s unit tests. Keep new re-exports of SDK shapes type-only for the same reason. ## Status spelling follows the SDK -`canceled`, one L — in code, in i18n keys (`pamStatusCanceled`), everywhere. The SDK's own +`canceled`, one L: in code, in i18n keys (`pamStatusCanceled`), everywhere. The SDK's own `TryFrom` conversions normalise incoming wire values onto these spellings, so the module never sees the other form. @@ -220,12 +235,12 @@ never sees the other form. `AccessRequestStatus` has no `activated` value. An activated request stays `approved` and is recognised by the `producedLeaseId` it minted, with `producedLeaseStatus` carrying that lease's state. Anything separating "approved, still to start" from "already running" must test -`producedLeaseId` rather than the status — that is what keeps the nav badge, the Pending list and +`producedLeaseId` rather than the status. That is what keeps the nav badge, the Pending list and the Start/Cancel actions off a grant the requester has already activated. `AccessLeaseStatus` carries a distinct `canceled` (the requester ended their own lease) next to `revoked` (an operator did), and `historyDisplayStatus` reads the label straight off -`producedLeaseStatus` — it does not scan the decision log. Optimistic patches must therefore write +`producedLeaseStatus`; it does not scan the decision log. Optimistic patches must therefore write the matching one: the holder's own `endLease` writes `canceled`, an approver's `revokeLease` writes `revoked`. `AccessLeaseView` additionally carries `termination: AccessLeaseTermination | undefined`, which spells out which happened and when; the row builders have no need for it, since @@ -236,12 +251,12 @@ which spells out which happened and when; the row builders have no need for it, `cipher_access_state()` and the list reads are one-shot, so nothing re-reads on its own. Two services drive every refresh: -- `AccessEventService` — the server's pushes for the active user, filtered to bare ticks: +- `AccessEventService`, the server's pushes for the active user, filtered to bare ticks: `accessChanged$` (`RefreshAccessRequest`) and `approverInboxChanged$` (`RefreshApproverInbox`, sent to everyone who can Manage the request's collection). -- `AccessRefreshService` — merges `accessChanged$` with this client's own mutations and fans it - out per cipher, so the cipher-view banner and `PamRevealedCipherService` react to a local - change and a remote one through exactly the same path. +- `AccessRefreshService`, which merges `accessChanged$` with this client's own mutations and + fans it out per cipher, so the cipher-view banner and `PamRevealedCipherService` react to a + local change and a remote one through exactly the same path. Page-level services subscribe to the pushes directly and reload: `MyAccessService` on `accessChanged$`, `ApproverInboxService` on both. Use `concatMap`, not `switchMap`: two pushes @@ -251,11 +266,11 @@ different moments. `AccessRequestDetailService` reads one request, so it re-fetc ### A lease running out -**Neither service fires when a lease reaches its `notAfter`** — no mutation here, and on the -server nothing happened at all. Left to them, an item open across its own expiry keeps the -credential revealed until a reload (PM-41837). With no event to wait for, every reader of -`activeLease` goes through `liveActiveLease(state, nowMs)` (`helpers/lease-liveness.ts`), which -drops a lapsed lease whatever the response said and fails closed on an unparseable `notAfter`. +**Neither service fires when a lease reaches its `notAfter`**: no mutation here, and on the server +nothing happened at all. Left to them, an item open across its own expiry keeps the credential +revealed until a reload (PM-41837). With no event to wait for, every reader of `activeLease` goes +through `liveActiveLease(state, nowMs)` (`bit-pam/src/helpers/lease-liveness.ts`), which drops a +lapsed lease whatever the response said and fails closed on an unparseable `notAfter`. Something has to move that clock. **Use one of the two that already tick; do not add a third.** The cipher-view banner owns a 1-second interval for its countdown, live exactly while there is an @@ -265,16 +280,17 @@ clock the badges run on, and only while the state they hold carries a live lease **A lapse is a cue to ask again, not proof the lease ended.** It may have been extended on another device, and no push need ever reach this tab (PAM-152). So every surface that caches a state -re-reads it when its lease lapses, through `rereadOnLapse` (`helpers/lease-liveness.ts`), and -judges the answer with `liveActiveLease` again. A server whose clock trails still hands back the -old `notAfter`, so the item still locks; only a genuinely later end keeps it open. +re-reads it when its lease lapses, through `rereadOnLapse` +(`bit-pam/src/helpers/lease-liveness.ts`), and judges the answer with `liveActiveLease` again. A +server whose clock trails still hands back the old `notAfter`, so the item still locks; only a +genuinely later end keeps it open. Both tick OUTSIDE the Angular zone, or NgZone never settles and `whenStable()` hangs for every host embedding a gated item. Signals carry out of it, so the banner and the pill need nothing more; `PamRevealedCipherService` re-enters explicitly, because the re-lock writes plain component fields on `vault-item-dialog.component.ts`. -`badgeState` is NOT clamped — only the SDK ranks it, so a lapsed `active` badge falls to +`badgeState` is NOT clamped: only the SDK ranks it, so a lapsed `active` badge falls to `AccessStateBadgeComponent`'s `remainingMs <= 0` recipe. The vault row has no clamp either, but it does re-read: on `AccessRefreshService`, and on a lapse through `rereadOnLapse` off the same shared ticker. @@ -284,15 +300,14 @@ shared ticker. PAM reaches non-commercial code only through injection tokens, each injected `{ optional: true }` on the OSS side so an unprovided token is inert. `provide-pam.ts` binds them all. In `libs/vault`: `CIPHER_VIEW_BANNER`, `ITEM_DETAILS_BADGE`, -`VAULT_CONTROLLED_ACCESS_FILTER` (the sidebar's "Controlled access" group plus the narrowing its -children apply to the item list), `VAULT_ITEM_FILTER` and `VAULT_ITEM_COLUMN` (the VFO1 vault -table's "Controlled access" chip and column, over the same state reads), and +`VAULT_ITEM_FILTER` and `VAULT_ITEM_COLUMN` (the vault table's "Controlled access" chip and +column, over the same state reads), and `SHARED_FOLDER_DECORATION` (the lock after a governed shared folder's name). In `apps/web`: -`VAULT_ROW_LEASE_BADGE` (one badge component for both cipher and collection rows — +`VAULT_ROW_LEASE_BADGE` (one badge component for both cipher and collection rows; collection rows show the "Privileged" pill straight off the collection's server-derived `hasEnabledAccessRule`), `VAULT_FILTER_GATED_COLLECTION_INDICATOR` (the lock glyph on a governed collection in the vault's Filters sidebar, reading that same -`hasEnabledAccessRule` off the sidebar's own collection node — `VaultFilterService` +`hasEnabledAccessRule` off the sidebar's own collection node; `VaultFilterService` carries it onto the copy `buildCollectionTree` makes through `new CollectionView(...)`, whose field initializer would otherwise reset it to `false`), `VAULT_GATED_COLLECTION_BANNER` (the notice above the item list naming that same @@ -302,7 +317,7 @@ to read), `COLLECTION_ACCESS_RULE_CALLOUT`, `PamNavBadgeService`, `VaultRowAccessActionsService` (the vault-row menu's cancel-request entry), `PAM_ROUTES` (the lazy loader for the user-scoped pages), and `PAM_ORG_ADMIN_ROUTE` (the `pam` path under `/organizations/{id}`, so the Admin Console's -redirect guard can land a member who holds only one of the PAM permissions — see "Routing and +redirect guard can land a member who holds only one of the PAM permissions; see "Routing and DI"). Add a seam rather than importing PAM from OSS code. @@ -324,14 +339,14 @@ and implement `HasUnsavedChangesDialog`: `unsavedChanges()` returns `false`, `tr default discard dialog, or options overriding it. Cancel just navigates and lets the guard ask. The guard stands down on lock and logout. -**The rotation fleet is a third authority, separate from rule authorship — do not reuse +**The rotation fleet is a third authority, separate from rule authorship. Do not reuse `canManageAccessRules` for it.** `canManageRotation` is Admin/Owner, or a Custom member holding `ManageRotation`, mirroring the server's `ManageAccessConnectorRequirement`. `ManageAccessRules` is authority over who may lease a credential, not over the connectors that rewrite it at the target system, so a Custom member holding only the rule permission who reaches `rotation/` gets a 403 from every request the page makes. -**Authoring a rule and deciding a request against it are separate authorities — do not +**Authoring a rule and deciding a request against it are separate authorities. Do not collapse them into one check.** `canManageAccessRules` (Admin/Owner, or a Custom member holding `ManageAccessRules`) gates the rules admin UI and nothing else; the approver surfaces gate on Manage over a collection @@ -345,7 +360,7 @@ Console.** No other `canAccessXTab` predicate implies either PAM surface, so `ca gained `canAccessAccessRulesTab` and `canAccessRotationTab` arms and `getOrganizationRoute` a matching landing arm; without them, the org route's guard bounces such a member to `/` and they never see the nav item. The landing arm reads `PAM_ORG_ADMIN_ROUTE` rather than hardcoding `pam`, -because OSS builds do not mount these pages — which is why `organizationRedirectGuard` runs its +because OSS builds do not mount these pages, which is why `organizationRedirectGuard` runs its callback inside an injection context. That lands them on `pam` itself, which is not a page: `pam-landing-route.ts` picks the section diff --git a/bitwarden_license/bit-web/src/app/pam/pam.allium b/bitwarden_license/bit-web/src/app/pam/pam.allium index 10801d3e2cb..8842cfe28d6 100644 --- a/bitwarden_license/bit-web/src/app/pam/pam.allium +++ b/bitwarden_license/bit-web/src/app/pam/pam.allium @@ -1,7 +1,7 @@ -- allium: 3 -- pam.allium --- Scope: Privileged Access Management (PAM) v0 — credential leasing for the +-- Scope: Privileged Access Management (PAM) v0, credential leasing for the -- web vault. Distilled from bitwarden_license/bit-web/src/app/pam and -- apps/web/src/app/pam. -- @@ -26,7 +26,7 @@ -- Excludes: -- - Vault encryption / cipher decryption (handled by the existing vault stack) -- - The vault-export stack itself (scope resolution, file generation, --- encryption) — the spec models only PAM's non-interference with it +-- encryption); the spec models only PAM's non-interference with it -- - Authentication / session management (auth stack) -- - Email templates and delivery: the spec models which action mails whom, not -- the template @@ -69,7 +69,7 @@ external entity Collection { name: String -- The access rule that gates PAM leasing for this collection, or null when leasing -- is disabled for it. The rule↔collection link lives HERE, on the collection, as a - -- single reference — which is what structurally limits a collection to at most one + -- single reference, which is what structurally limits a collection to at most one -- governing rule (there is no set to hold a second). Deleting a rule clears this -- link (a hard delete), leaving the collection ungoverned until it is reassigned to -- a new rule. @@ -89,7 +89,7 @@ external entity CollectionMembership { -- ---------------------------------------------------------------------------- -- The non-sensitive projection of a Cipher the server returns in a GATED --- response — enough for the client to render the vault row and the request / +-- response, enough for the client to render the vault row and the request / -- banner UI without the protected secret. It carries NO sensitive fields (no -- username, password, note, card, identity, TOTP or custom fields). Only a -- single-item read by an ungated caller, or under a live lease, returns the full @@ -189,7 +189,7 @@ variant IpAllowlist : Condition { -- of an existing lease is not evaluated against them (PM-42500). -- -- - AccessLease constraints (`single_active_lease`, `max_lease_duration`, and the --- extension settings) do NOT gate the decision — they shape the LEASE. The +-- extension settings) do NOT gate the decision; they shape the LEASE. The -- window cap is checked at submit, the slot at lease start against state beyond -- the request (the active-lease set for the cipher), and the extension settings -- when the holder extends. Many members can be approved and hold approved @@ -229,7 +229,7 @@ entity AccessRule { -- AccessLease constraint: the most one extension may add. Null refuses every -- extension, so a rule that allows extensions must set it. max_extension_duration: Duration? - -- AccessLease constraint: when true, the rule asks for a per-cipher singleton — only + -- AccessLease constraint: when true, the rule asks for a per-cipher singleton: only -- one AccessLease active at a time for a given cipher, across all granted users. -- Honored by the same union/OR logic as cipher gating: the singleton binds for a -- member only when EVERY collection through which they reach the cipher is @@ -333,15 +333,15 @@ entity AccessRequest { -- its approval time. resolved_at: Timestamp? when status != pending -- The approver, or null for a system / access-rule auto-decision. Persists - -- once set — through activation and unactivated expiry — for the audit trail. + -- once set, through activation and unactivated expiry, for the audit trail. approver: User? when status != pending approver_comment: String? when status != pending - -- The lease minted when this approved request was activated (at most one — + -- The lease minted when this approved request was activated (at most one, -- single use). Resolved from the inverse AccessLease.request reference, so it stays -- correct for the request's whole life, whatever the lease's later status. lease: AccessLease with request = this - -- The single upper bound on this request being actionable at all — deciding a + -- The single upper bound on this request being actionable at all, deciding a -- pending request AND starting an approved one: the window end. Past it a -- request that is still pending, or approved and never started, reads as expired -- (PendingRequestExpires / ApprovedRequestExpiresUnactivated). Nothing else ages @@ -456,7 +456,7 @@ config { -- A member opens a cipher. Access in Bitwarden is the UNION of the member's -- collection memberships: the member reaches the cipher through any collection -- they belong to that contains it. Gating therefore applies only when EVERY such --- path is gated — every collection through which THIS member reaches the cipher +-- path is gated: every collection through which THIS member reaches the cipher -- carries an enabled AccessRule. If even one of those collections has no rule, -- the member already has ungated access, so the cipher opens normally and the -- rule on the other collection cannot gate it. This is a real bypass, and it is @@ -609,7 +609,7 @@ rule CipherOpenWithApprovedRequest { -- active lease. Opening offers to start the lease rather than creating a -- duplicate request: the partial view opens and the banner offers Start -- access (or shows the upcoming window when a scheduled start has not - -- arrived). Activation stays an explicit member action — see the + -- arrived). Activation stays an explicit member action; see the -- MemberActivatesLease section. when: OpenCipher(caller, target_cipher) let member_memberships = CollectionMembership where member = caller @@ -648,8 +648,8 @@ rule CipherOpenWithApprovedRequest { rule CipherOpenPassthrough { -- Opens normally: either the member is in no collection containing the -- cipher, or they reach it through at least one collection with no enabled - -- rule — so gating does not apply (union-based collection access; the bypass - -- is not surfaced to admins — see RuleBypassableCiphers). + -- rule, so gating does not apply (union-based collection access; the bypass + -- is not surfaced to admins; see RuleBypassableCiphers). when: OpenCipher(caller, target_cipher) let member_memberships = CollectionMembership where member = caller and collection in target_cipher.collections @@ -757,10 +757,10 @@ rule ManagedCollectionsExportExcludesGated { rule MemberSubmitsAccessRequest { -- The member submits the Request Access modal for a gated cipher. THIS is - -- where the AccessRequest is created — not at cipher-open. The activation + -- where the AccessRequest is created, not at cipher-open. The activation -- window is pinned here for BOTH shapes: a proposed window (window_start + -- window_end) makes it a scheduled request; otherwise the window defaults to - -- [now, now + rule-derived duration] — an on-demand request, promotable + -- [now, now + rule-derived duration], an on-demand request, promotable -- immediately. The requester never names a duration: the on-demand window -- length comes from the pinned rule, and the lease minted at activation runs -- to the window end either way (see ActivateLease). Evaluation runs @@ -964,9 +964,9 @@ rule MemberRequestsLeaseExtension { -- A request is created and becomes ready for evaluation in one step when the -- member submits the Request Access modal (MemberSubmitsAccessRequest). An --- extension never comes here: it is created already decided. Every gated open — --- including IP-allowlist-only rules --- — goes through the modal/submit. A rule with no human_approval condition +-- extension never comes here: it is created already decided. Every gated open, +-- including IP-allowlist-only rules, +-- goes through the modal/submit. A rule with no human_approval condition -- resolves synchronously on submit, so the submit response can already carry an -- approved request. Its automated conditions were already checked by the submit -- itself, which refuses on a failure and saves nothing, so evaluation never meets a @@ -982,14 +982,14 @@ rule MemberRequestsLeaseExtension { -- still applies. -- -- The reasoning, stated plainly because the consequence is not small: the decision --- that mattered was the original grant, and an extension re-opens no new access — +-- that mattered was the original grant, and an extension re-opens no new access: -- it lengthens access the member already holds, over the same credential, under the -- same rule. The controls that remain on it are the rule's opt-in (may this lease -- be extended at all), the per-increment cap, and one extension per lease. What -- this gives up is that an -- ip_allowlist can no longer bound access to the admitted network once a lease -- exists: a member who obtained a lease from inside the allowlist may extend it --- from anywhere. That is a deliberate trade, not an oversight — see the +-- from anywhere. That is a deliberate trade, not an oversight; see the -- ip_allowlist open question (PAM-205). -- -- The two evaluation rules below partition the pending space exactly once, so no @@ -1000,7 +1000,7 @@ rule MemberRequestsLeaseExtension { rule RequestReadyForEvaluationOnCreation { -- Requests are only ever created by a member submitting the Request Access -- modal (MemberSubmitsAccessRequest) or by a lease extension - -- (MemberRequestsLeaseExtension) — never speculatively at cipher-open. Only the + -- (MemberRequestsLeaseExtension), never speculatively at cipher-open. Only the -- first is created pending; it is, by construction, one the member has -- submitted, and is immediately ready for evaluation. when: request: AccessRequest.created @@ -1051,7 +1051,7 @@ rule RouteToHumanApprovers { -- ---------------------------------------------------------------------------- rule ApproverApprovesRequest { - -- The approver approves the request. No lease yet — the requester activates it + -- The approver approves the request. No lease yet: the requester activates it -- (ActivateLease) when they actually need access. when: ApproverDecides(approver, request, verdict, comment?) requires: request.status = pending @@ -1134,8 +1134,8 @@ rule ApproverRetractsRequest { -- ---------------------------------------------------------------------------- -- An approved request is activated via MemberActivatesLease. Activation is ALWAYS an --- explicit member action — a Start click on MyAccessRequestsPage, the --- CipherViewBanner or the RequestDetailView — never a side effect of opening the +-- explicit member action: a Start click on MyAccessRequestsPage, the +-- CipherViewBanner or the RequestDetailView, never a side effect of opening the -- item, and never automatic: -- minting the lease requires the requester to be online to drive the client (this -- is why even a scheduled request must be started by the requester inside its @@ -1146,7 +1146,7 @@ rule ApproverRetractsRequest { -- submitted_at + rule-derived duration] for on-demand). From here on they are -- UNIFORM: one start rule (ActivateLease), one eligibility window -- [lease_not_before, actionable_until], one unactivated-expiry rule --- (ApprovedRequestExpiresUnactivated), and one lease-END formula — the lease +-- (ApprovedRequestExpiresUnactivated), and one lease-END formula: the lease -- runs from the moment of activation (never backdated to the window start) to -- the window end. The rule's durations already shaped and capped the window at -- submit; neither plays a part at activation. @@ -1154,17 +1154,17 @@ rule ApproverRetractsRequest { -- single_active_lease contention is resolved here, at start, since this is when -- the lease comes into being: if RuleAllowsLease is false (the cipher's single slot -- is already taken) the start is simply rejected and the approved request stays --- activatable for a manual retry — there is no queue. A start will likewise be +-- activatable for a manual retry; there is no queue. A start will likewise be -- refused while the org is under a LeasingFreeze (the kill switch's optional -- block-new-leases), once that is built (see the PLANNED section). Automated -- conditions (e.g. ip_allowlist) are re-checked here too: a mismatch at start --- rejects the activation. Extensions never reach here — +-- rejects the activation. Extensions never reach here: -- they apply in place as they are created (MemberRequestsLeaseExtension). -- -- A failed activation NEVER consumes the approval. The request counts as started -- (`activated`) ONLY once the start mints its lease (ActivateLease); the status --- stays `approved` throughout. Any rejected start — automated-condition mismatch, --- single_active_lease contention, leasing freeze, or a lapsed window — leaves the +-- stays `approved` throughout. Any rejected start (automated-condition mismatch, +-- single_active_lease contention, leasing freeze, or a lapsed window) leaves the -- request approved with no lease, and activatable for a retry up to -- actionable_until (the window end). This lease↔request correspondence is pinned by -- the AtMostOneLeasePerActivatedRequest and NoLeaseWithoutActivatedRequest @@ -1264,8 +1264,8 @@ rule LeaseActivationRejected { -- Expiry and an early end are the ways a lease leaves `active`, and a single -- transition out of `active` can have only one terminal outcome. Rather than -- have the autonomous expiry timer, the holder's own end and an operator's --- revoke each write `status` directly — racing each other for the terminal value --- — all three emit a LeaseSettles event and SettleLease owns the single +-- revoke each write `status` directly, racing each other for the terminal value, +-- all three emit a LeaseSettles event and SettleLease owns the single -- transition. Expiry takes precedence: an early end is only emitted while -- strictly in-window (now < not_after), so once not_after has passed the only -- signal that can arrive is the expiry one and the lease deterministically @@ -1344,8 +1344,8 @@ rule ApproverRevokesLease { rule SettleLease { -- The single owner of the transition out of `active`. Driven by exactly one - -- emitter — the autonomous LeaseExpires timer, or an in-window - -- MemberEndsOwnLease or ApproverRevokesLease — never two, since an early end is + -- emitter (the autonomous LeaseExpires timer, or an in-window + -- MemberEndsOwnLease or ApproverRevokesLease), never two, since an early end is -- rejected at/past not_after. No ender means the lease lapsed on its own -- (expired); the holder means they gave it back (canceled); anyone else means -- an operator cut it off (revoked). The reason, if any, goes to the originating @@ -1509,7 +1509,7 @@ rule OrgAdminDeletesAccessRule { requires: CanManageAccessRules(admin, target_rule.organization) -- Hard delete: clear the rule's collection links and every request pin to it, -- then remove the rule. Each governed collection survives, now ungoverned. A - -- deleted rule is simply gone — no gating / admin read can find it, so none + -- deleted rule is simply gone: no gating / admin read can find it, so none -- needs to filter it out. The name lookup for the rule_deleted audit event is -- supplied by the delete command (captured before the delete), so the row need -- not survive. @@ -1568,7 +1568,7 @@ deferred CanManageAccessRules -- see: server ManageAccessRulesRequirement -- `EligibleRevokers(lease)`: the operators who may revoke someone's active lease: -- EligibleApprovers for the lease's request, plus the lease's org admins. Org --- admins may revoke any single lease directly (from the governance dashboard) — +-- admins may revoke any single lease directly (from the governance dashboard); -- they are not limited to the org-wide kill switch. Holding the lease does not put -- the holder in this set; they end it through MemberEndsOwnLease, which settles to -- canceled. A holder who is in the set anyway, because they can Manage the @@ -1612,15 +1612,15 @@ deferred RuleAutomatedConditionsPass -- see: server SubmitAccessRequestComman -- breaking ties on rule id (lowest id wins) so the choice is total and stable. -- Returns null for an empty set. The candidate set (enabled rules on -- the collections through which the member reaches the cipher) and the oldest-wins --- property are computed STRUCTURALLY at the call sites — CipherOpenRequiresAccessRequest --- and MemberSubmitsAccessRequest — where a requires clause asserts no candidate is +-- property are computed STRUCTURALLY at the call sites, CipherOpenRequiresAccessRequest +-- and MemberSubmitsAccessRequest, where a requires clause asserts no candidate is -- older via creation_date. This selector exists only because a where-query yields -- an unordered Set with no positional `.first`, and to carry the id tie-break, -- which the spec language has no total-order primitive to express. -- -- WHY oldest-wins (do not reintroduce the old behaviour): resolution favours -- neither an automatic grant over one needing human approval nor least-restriction --- of any kind — the oldest rule's conditions decide outright. Semantic consequence: +-- of any kind: the oldest rule's conditions decide outright. Semantic consequence: -- a newer auto-approve rule on one path does NOT pre-empt an older human-approval -- rule on another path (or vice versa). A member may be routed to an approver even -- though a newer path would have auto-granted, because the older rule governs. This @@ -1634,7 +1634,7 @@ deferred RuleAutomatedConditionsPass -- see: server SubmitAccessRequestComman -- later edits to the pinned rule do apply at activation and extension. The -- oldest-wins property is therefore asserted at the creation transition only. -- --- This is distinct from — and does not change — the union/OR policy that decides +-- This is distinct from, and does not change, the union/OR policy that decides -- WHETHER the cipher is gated at all (an ungated path bypasses gating; see -- CipherOpenPassthrough / RuleBypassableCiphers) or the union/OR logic for -- single_active_lease (see SingleActiveLeaseApplies / RuleAllowsLease). @@ -1643,14 +1643,14 @@ deferred RuleAutomatedConditionsPass -- see: server SubmitAccessRequestComman deferred oldest_rule -- see: server-side GoverningRuleResolver -- `RuleBypassableCiphers(rule)`: the ciphers in this rule's collections that a --- member could also reach through some collection with NO enabled access rule — +-- member could also reach through some collection with NO enabled access rule, -- so the rule's gating does not actually protect them (see the cipher-open -- gating logic). Empty when the rule's collections share no ciphers with ungated -- collections. Computed server-side (it must scan ciphers and their collection -- membership). -- -- This is the PER-PATH bypass. The org-wide export permission is a separate, --- per-caller one that no rule-level warning captures — see +-- per-caller one that no rule-level warning captures; see -- VaultExportBypassesLeasing. -- IMPLEMENTED with a deliberate narrowing: the server answers the ungated COLLECTIONS, not the -- ciphers. Naming a cipher requires decrypting it from the caller's own vault, and an admin outside @@ -1722,7 +1722,7 @@ deferred ManagedExportCiphers -- see: vault export stack (outside PAM) -- which `member` reaches `cipher` is governed by an enabled AccessRule whose -- single_active_lease is set. By the union/OR rule (the same logic that lets an -- ungated path bypass gating), the singleton binds only when no path offers an --- escape — no path is ungated and none is governed by a rule without +-- escape: no path is ungated and none is governed by a rule without -- single_active_lease. Evaluated independently of which rule governs the request -- decision: it is a property of the member's whole set of paths to the cipher, not -- the single resolved gating rule. @@ -1732,14 +1732,14 @@ deferred SingleActiveLeaseApplies -- see: server-side lease start / rule eval -- When SingleActiveLeaseApplies(member, cipher) holds (all of the member's paths to -- the cipher are single_active_lease-governed) the singleton binds: returns false if -- any other lease is already active for this cipher (across all users), so a second --- cannot start. When it does not hold — the member has at least one ungated or --- non-single_active_lease path — the member is unconstrained and this is always +-- cannot start. When it does not hold (the member has at least one ungated or +-- non-single_active_lease path), the member is unconstrained and this is always -- true. Checked at lease start (ActivateLease) against the -- member's current paths to the request's cipher, not at approval, since that is when -- the lease comes into being. -- -- Contention policy: when the cipher's slot is taken the start is rejected and the --- approved request stays `approved` — the member retries when it frees, bounded by +-- approved request stays `approved`; the member retries when it frees, bounded by -- the activation window. No server-side queue; the member polls, with availability -- surfaced by pre_check (can_start_lease / slot_frees_at, PM-42446) in -- RequestAccessModal and by the cipher-view banner. @@ -1801,11 +1801,15 @@ actor CollectionManager { surface CipherViewBanner { -- The requester's entry point on an open gated cipher: renders exactly one of - -- five states. Unlicensed comes first and replaces every other state, an active + -- seven states. Unlicensed comes first and replaces every other state, an active -- lease included (CipherOpenBlockedUnlicensed): it explains the block and offers - -- nothing. Otherwise: active lease (countdown, extend, end), approved request - -- (start, withdraw), pending request (withdraw), or none of those (request - -- access, which folds out RequestAccessModal inline). Also the surface that reveals the + -- nothing. Otherwise: active lease (countdown, extend, end; in its last five + -- minutes, ENDING_SOON_THRESHOLD_MS, the design shows the countdown alone with no + -- actions), approved request (start only), pending request (withdraw), + -- unavailable (the rule refuses a request right now, so it offers nothing), + -- access ended (a held lease ran out while the item was open; it offers request + -- access again where the rule allows one), or none of those (request access, + -- which opens RequestAccessModal). Also the surface that reveals the -- credential in place the moment a lease becomes active, without reopening the -- item. See cipher-view-banner.component, bound to the CIPHER_VIEW_BANNER seam; -- the reveal itself goes through Vault's RevealedCipherService. @@ -1836,13 +1840,13 @@ surface CipherViewBanner { and request.status = approved and request.lease = null and HoldsPamSeat(viewer, target_cipher.organization) - -- Withdraw, on the pending and approved states. Hidden behind the unlicensed - -- block here, but the vault row's menu (VaultRowAccessState) and the My - -- requests tab still offer it, since giving access back needs no seat. + -- Withdraw, on the pending state only. The approved card offers just Start + -- access; the vault row's menu (VaultRowAccessState) and the My requests tab + -- still withdraw an approved request, and offer it behind the unlicensed + -- block, since giving access back needs no seat. MemberCancelsRequest(viewer, request) when request.requester = viewer and request.cipher = target_cipher - and (request.status = pending - or (request.status = approved and request.lease = null)) + and request.status = pending and HoldsPamSeat(viewer, target_cipher.organization) -- Extending and ending the lease are offered here as well, through -- extend-lease-dialog.component; ActiveLeasesPage states them once for every @@ -1872,9 +1876,9 @@ surface VaultRowAccessState { or (request.status = approved and request.lease = null)) @guidance - -- Filters: the sidebar's "Controlled access" group narrows the item list by - -- the same badge. "Privileged" keeps every item gated for the viewer, and - -- "My requests" keeps those with a pending, ready or active badge. + -- Filters: the vault table's "Controlled access" chip narrows the item list by + -- the same badge, one option per badge state, with "In use" and "Ending soon" + -- splitting an active lease. Selected options combine with OR. -- -- Collection level: the collection row's "Privileged" pill, the sidebar lock -- and the banner above a governed collection's item list describe the @@ -1906,11 +1910,14 @@ surface RequestAccessModal { -- which creates it (MemberSubmitsAccessRequest). Dismissing without submitting -- creates nothing. -- - -- Implemented as a fold-out INSIDE CipherViewBanner rather than a separate modal, - -- so the requester never loses sight of the item they are asking for. Which fields - -- it collects comes from pre_check: a duration alone on the automatic path, a - -- window plus a required reason on the human path. The name is kept because the - -- copy keys (requestAccessModal*) are shared with it. + -- Implemented inside CipherViewBanner rather than as a separate modal route, so + -- the item stays in view: in the web vault's item dialog the form folds out in + -- place under the banner, and in the extension popup (CIPHER_VIEW_BANNER_LAYOUT + -- `popup`) it opens in a bottom sheet over a dimmed overlay + -- (request-access-sheet.component). Which fields it collects comes from + -- pre_check: a duration alone on the automatic path, a window plus a required + -- reason on the human path. The name is kept because the copy keys + -- (requestAccessModal*) are shared with it. facing requester: Member context target_cipher: Cipher @@ -1941,7 +1948,7 @@ surface RequestAccessModal { -- span the server will accept. gating_rule.default_lease_duration when not has_ungated_path gating_rule.max_lease_duration when not has_ungated_path - -- Whether a lease could actually be started right now — i.e. the per-cipher + -- Whether a lease could actually be started right now, i.e. the per-cipher -- single_active_lease slot is currently free for this member. Only binds when -- all of the member's paths to the cipher are single_active_lease-governed -- (union/OR); otherwise always startable. Lets the modal warn that an @@ -1963,8 +1970,8 @@ surface RequestAccessModal { surface MyAccessRequestsPage { -- "My requests": the caller's own AccessRequest rows, bounded by the shared -- history window. Implemented as two tabs of the Access requests page rather than - -- one list — my-requests-tab.component holds what is still actionable (pending - -- requests and active leases) and history-tab.component holds what has resolved — + -- one list: my-requests-tab.component holds what is still actionable (pending + -- requests and active leases) and history-tab.component holds what has resolved, -- because the two carry different actions. Each row links to the single-request -- view (RequestDetailView). facing viewer: Member @@ -2023,7 +2030,8 @@ surface ActiveLeasesPage { -- No page of its own. Both actions it provides ARE reachable: the -- "Active access" section of my-requests-tab.component ends a lease, and -- cipher-view-banner.component ends or extends the lease on the item itself - -- (through extend-lease-dialog.component). This surface is kept as the domain + -- (through extend-lease-dialog.component) until its last five minutes, when the + -- banner drops both actions. This surface is kept as the domain -- statement of what a lease holder may do to their own lease, independently of -- which screen offers it. facing viewer: Member @@ -2068,7 +2076,7 @@ surface ApproverInbox { exposes: -- Pending bucket: requests the approver may decide. Extensions never appear - -- here — since PM-42500 they are approved at creation and never rest at + -- here: since PM-42500 they are approved at creation and never rest at -- `pending` (see MemberRequestsLeaseExtension). An approver sees a member's -- first grant and nothing after it. for r in AccessRequest where status = pending @@ -2226,7 +2234,7 @@ surface CollectionAccessRuleCallout { -- collection's items so an admin editing WHO can reach a collection can see that a -- rule already governs WHEN. Read-only and informational: it grants nothing and -- blocks nothing, so a failed read simply hides it. Only rendered while editing an - -- existing collection — there is nothing to gate before one exists. See + -- existing collection: there is nothing to gate before one exists. See -- collection-access-rule-callout.component, bound to the -- COLLECTION_ACCESS_RULE_CALLOUT seam. -- @@ -2256,7 +2264,7 @@ surface CollectionAccessRuleCallout { invariant AtMostOneLeasePerActivatedRequest { -- Single-use approved request: a request that has a lease has exactly one, - -- and an extension never has any — it applies by extending the parent in place + -- and an extension never has any: it applies by extending the parent in place -- and never mints a lease of its own. An approved request with no lease is one -- that has not started. for request in AccessRequest: @@ -2274,10 +2282,10 @@ invariant NoLeaseWithoutActivatedRequest { } invariant AtMostOneActiveLeasePerRequesterCipher { - -- A member holds at most one active lease per cipher. Holds transitively — - -- MemberSubmitsAccessRequest is blocked while an active lease exists, an + -- A member holds at most one active lease per cipher. Holds transitively + -- (MemberSubmitsAccessRequest is blocked while an active lease exists, an -- approved request is single-use, and an extension extends the parent in - -- place rather than minting a lease — but is pinned here as a first-class + -- place rather than minting a lease), but is pinned here as a first-class -- obligation because reads rely on it: the `.first` on active_leases in -- CipherOpenWithActiveLease is deterministic only because the set is a -- singleton. @@ -2328,7 +2336,7 @@ invariant SingleActiveLeaseRespected { -- cipher cannot both be active when the singleton binds for both requesters (every -- path each requester has to the cipher is single_active_lease-governed). A requester -- with an ungated or non-single_active_lease path is unconstrained, so such a - -- lease may legitimately coexist — a deliberate bypass, like RuleBypassableCiphers. + -- lease may legitimately coexist, a deliberate bypass, like RuleBypassableCiphers. for a in AccessLease: for b in AccessLease: a != b @@ -2346,7 +2354,7 @@ invariant SingleActiveLeaseRespected { invariant OrgUniqueRuleNames { -- Storage constraint (intentional gap), silent in the rule model but enforced by -- the implementation: a live rule's name is unique within its organization - -- (create and update reject a duplicate, compared case-insensitively — the spec + -- (create and update reject a duplicate, compared case-insensitively; the spec -- has no case-fold primitive, so this expresses the distinctness only). Names are -- otherwise bounded to 1..256 characters (see OrgAdminCreatesAccessRule). for a in AccessRule: @@ -2442,7 +2450,7 @@ surface GovernanceDashboard { -- All active leases in scope, surfaced by GET /leases/active. AccessLease where collection.organization = org and status = active -- All recently-ended leases (expired, revoked or canceled) in scope, within the - -- shared history window — surfaced by GET /leases/history. A lease's end is its + -- shared history window, surfaced by GET /leases/history. A lease's end is its -- ended_at (revoked or canceled) or its not_after (expired). AccessLease where collection.organization = org and ((status in {revoked, canceled} and ended_at >= now - config.history_window) @@ -2503,7 +2511,7 @@ open question "Should a submit the automated conditions refused notify anyone be open question "Should expiry be announced? Nothing is sent when a pending request lapses undecided (the approvers who never acted are not told), when an approved request lapses unused (the requester is not told), or when a lease reaches its end. Expiry is derived when read, so any notice would need a sweep or a scheduled send." --- RESOLVED — what bounds a lease's cumulative life once extensions need no +-- RESOLVED: what bounds a lease's cumulative life once extensions need no -- approval (PM-42500). Recorded because the reasoning matters, not just the outcome. -- -- Before PM-42500 every extension ran the full evaluation, so on a human-approval @@ -2518,7 +2526,7 @@ open question "Should expiry be announced? Nothing is sent when a pending reques -- After that the member makes a fresh request, which runs the full evaluation, -- human approval included. Whether one is the right number is PAM-212. --- RESOLVED — org suspension. Governance keeps working while an organization is +-- RESOLVED: org suspension. Governance keeps working while an organization is -- suspended; members' leases stop releasing. -- - Governance: the collection-scoped reads and actions (approver inbox, lease -- lists, request details, decide, cancel, revoke) resolve manageable collections @@ -2531,31 +2539,31 @@ open question "Should expiry be announced? Nothing is sent when a pending reques -- releasing its cipher until the organization is re-enabled. That is the safe -- side for a suspended organization. --- RESOLVED — when a member reaches a cipher through multiple gated collections +-- RESOLVED: when a member reaches a cipher through multiple gated collections -- carrying different enabled rules, WHICH rule governs was previously undefined / --- fragile (an automatic-favoured union/OR pick). Locked down: the OLDEST rule wins --- — the enabled, non-deleted rule with the earliest creation_date among the +-- fragile (an automatic-favoured union/OR pick). Locked down: the OLDEST rule wins, +-- the enabled, non-deleted rule with the earliest creation_date among the -- member's gated paths to the cipher (ties broken stably on rule id). Deterministic, -- with no favouring of automatic grants over human approval. Resolution happens -- once, at request submit time, and the resolved rule is PINNED on the AccessRequest -- (its RuleId stored at creation). Downstream reads the pinned rule as it stands now -- and never re-resolves to a different rule while the pin stands; only a rule delete -- clears the pin (see the AccessRequest.rule field). Trade-off, stated deliberately: a --- newer auto-approve rule no longer pre-empts an older human-approval rule — +-- newer auto-approve rule no longer pre-empts an older human-approval rule: -- determinism over least-restriction. See the oldest_rule selector and the --- AccessRequest.rule field. NOTE: this is distinct from — and does not change — the +-- AccessRequest.rule field. NOTE: this is distinct from, and does not change, the -- union/OR policy that decides WHETHER a cipher is gated at all (one ungated path -- bypasses gating; see RuleBypassableCiphers) or the union/OR logic for -- single_active_lease (see SingleActiveLeaseApplies). --- RESOLVED — deleting a rule that requests are pinned to (server #8002, the same day +-- RESOLVED: deleting a rule that requests are pinned to (server #8002, the same day -- the spec was first written). The delete clears every pin to the rule before -- removing it, instead of failing on the request's foreign key or being blocked: the -- pin is provenance, not authority, and the audit trail already snapshots the rule's -- name. A request left without a pin re-resolves wherever the pin would have been read -- (see AccessRequest.rule and OrgAdminDeletesAccessRule). --- RESOLVED — extending a lease whose rule was deleted. A lease has no rule of its +-- RESOLVED: extending a lease whose rule was deleted. A lease has no rule of its -- own: its rule is its originating request's pin, which the delete clears. The -- extension then re-resolves against the member's current paths. When no rule -- governs, the item no longer needs a lease and the extension is refused ("This item