Repository navigation
Access Model
Since 2026-08-17 the portal decides every access question from one DynamoDB table, Access, in which grants are stored exactly as an admin granted them: a principal (a user or a group) to a target (a role in an account, or a private-network resource). A user's effective access is their own unexpired rows plus the rows of every group they belong to, and that union is computed in exactly one module that every reader calls. Absence is default-deny, a request never confers access, and a preference can never become a grant. This page summarizes the model; the row-level rules and lifecycles live in the deployment README, and Architecture shows where the vend itself happens.
PK principal
|
SK target
|
Attributes | Meaning |
|---|---|---|---|
user#<sub> or group#<groupId>
|
role#<account>#<roleName>, resource#<resourceId>, plugin#<pluginId>#<account>#<user|admin> or share#<shareId>
|
grantedBy, grantedAt, expiresAt?; on user rows expiringSeen?, expiredSeen? and expiryLoggedAt?; share rows also carry ttl
|
A grant to that principal. A plugin# row authorizes only when pluginAccess.ts finds its binding available |
sharedef |
share#<shareId> |
owner, label, port, siteId, expiresAt, ttl
|
A dev share's definition. Not a user or group, so never anyone's access |
user#<sub> |
member#<groupId> |
addedBy, addedAt
|
Group membership |
user#<sub> |
pref#role#<account>#<roleName> and other pref# keys |
profileName?, roleLabel?, the auto-vend star; also the pref#presence, pref#adminReview, pref#network and pref#notifications rows |
Per-user preferences. A different SK, so never a grant |
-
<sub>is the Cognitosubfor humans and the app client id for service users. - The
byTargetGSI (targettoprincipal) answers "who holds X" for users and groups, and "who is in group g" viamember#<g>. - The Groups table keeps only
{groupId, name, description, createdAt, createdBy}; a group's bundle and its members are Access rows. Nothing is materialized per member. - The v1
GrantsandResourceGrantstables (per-user rows) were unread since v2 and leftDataStackin 0.2.0. - Requests are the conversation ("may I?"); Access is the answer. Approving a request writes an Access row; the request row itself grants nothing. The Audit and Revocations tables are never read for a decision.
Why v2 replaced v1 (materialized viaGroup rows could not express "held directly and via a group"): Access model v2.
flowchart LR
U["user principal"] --> D["own role and resource rows, unexpired only"]
U --> M["member rows"]
M --> G["each group's rows, unexpired only"]
D --> E["effective access"]
G --> E
E --> R["vending, accounts and resources listings, request eligibility, reapproval sweep, expiry notices, users directory, grantee lists, ACL reconciler"]
effectiveAccess(userId) is the union of the user's direct rows and the rows of every group in their memberships. A row counts only while unexpired, whoever holds it (admin-granted group rows carry no expiry; a dev share's do). The function lives in packages/infra-client/lambdacode/api/services/access.ts (effectiveAccess, effectiveFor, holdersOf, snapshot) and every reader goes through it. Cost is one Query on the user's partition (grants, memberships and prefs in one page) plus one Query per group; the vending hot path (effectiveFor, via effectiveForMany) replaces the per-group Queries with one BatchGet of the (group, target) keys, so a vend is two reads. The direct and viaGroups labels the admin views show are derived at read time.
Losing access is a row delete, so a notice cannot ride on the row. Every mutation that can end access (a direct revoke, leaving a group, a bundle shrinking, a group, role or resource delete, a reapproval lapse) goes through accessNotices.withAccessDiff, which diffs each affected user's effective targets before and after and writes a Revocations notice only for what was really lost.
- An admin grant, a bulk grant or an approval can carry
durationHoursfrom fixed presets (1 hour to 30 days); omitting it means standing access. Re-granting an existing temporary grant extends it. - An expired row is kept, not deleted. Vending denies it, audited as
EXPIRED(distinct fromNO_GRANT), it stops listing on the accounts page, and re-approval overwrites the row. - In the request picker an expired grant no longer blocks (re-request = renewal) and an unexpired temporary one can be re-requested (an extension ask); only long-term access blocks a new request.
- The bell is two-phase: one notice when "expiring soon" (within the smaller of 24 hours and half the lifetime) and one for 7 days after expiry, with separate
expiringSeenandexpiredSeenflags. - Resource grants follow the same lifecycle; the network closes on the reconciler's next pass.
Detail: Temporary grants and expiry lifecycle.
A daily sweeper reviews standing grants (no expiresAt), role and resource rows alike, for users and for group bundles (one review per group and target, decided once for all members). Interval 12 months, grace 14 days. Approving a REAPPROVAL request re-writes the grant and restarts the clock; denying it revokes. Grace is experienced, not computed: auto-revocation happens only after a raised review sat open for the full 14 days, and is recorded as a denial by system:reapproval so the audit shows it was not a person.
Two raise-only yearly reviews ride the same sweep and are never acted on automatically: service users (deny deletes the service user) and admins (deny demotes from the admins group; refused for the last human admin). Pending role and resource reapprovals can carry usage counts from the audit log when the Requests page asks for them. Humans get a lastSeenAt presence stamp as a pref#presence row. Detail: Periodic reapproval.
A group is a bundle of roles and resources plus a member list, all as Access rows. Adding a member adds one member# row and the member inherits the whole bundle; removing them removes that row, and the loss diff decides the notice. A direct grant and group access are independent: revoking a direct grant never touches the group's promise, and a direct grant next to group access keeps its own expiry. Deleting a group pulls its grants from all members while direct or other-group access survives. The one surviving "never downgrade" rule: a temporary direct grant never overwrites a long-term direct one. Bulk revoke removes direct grants only; a pair held through a group is reported as skipped ("No direct grant to revoke"), never refused. Detail: Group edge rules.
The ~/.aws/credentials profile name for a user and role is resolved by the API in one place (services/profileNames.ts, returned by GET /accounts) and the desktop writes exactly that string. Order: the user's own override; else the account's admin-set profile name, only when the user holds exactly one role in that account; else the role's admin-set name; else <accountNumber>-<roleName> slugged. Admin-set names are unique across the platform, case-insensitively. The override, the personal role label and the auto-vend star are pref#role#... rows: plain upserts that survive a revoke and can never create access. Detail: Profile names and Per-role preferences.
A service user is a Cognito app client with a secret using the OAuth client_credentials flow (scope api/invoke, tokens live one hour). Its token's sub is the client id, so its grants are ordinary rows under user#<clientId> and vending, listings, revocation and audit work unchanged. Its registry row carries its scopes — aws, network, shares (the same route table personal access tokens use), admin.read.all (the GET routes under /admin) and admin.write.all (every /admin route; implies the reads) — read on every request; only the admin scopes make it an app admin, so only an admin.write.all secret is a full admin credential (rows from before scopes existed read as the full set aws, network, shares, admin.write.all; routes outside the scope table, such as requests, notifications and plugin discovery, are reachable by no service user). Authentication also requires the ServiceUsers registry row to exist, so deleting one locks it out on its next request and narrowing its scopes holds from the next request; the registry never decides grants. An admin.write.all service user manages service users like a human admin. Cognito cannot re-show a secret, so rotation creates a new client behind the same name with the grants copied, and both work until the old one is removed. No caller can delete or demote the last human admin. Detail: Service users.
Each target role's trust policy pins the audience and a role-scoped subject: the issuer mints sub = "<account>/<role>/<userId>" and the condition is StringLike <issuer>:sub = "<account>/<role>/*". A leaked or replayed token therefore works against exactly one role in one account. Rollout order is load-bearing: CredsStack first (the pin is additive), then each target account's roles stack, then a vend per account. lib/__tests__/target-account-stack.test.ts asserts the condition. Detail: Sub-pinning; the trust side is in Security Posture.
From the repo's working rules:
- One
Accesstable; grants are stored exactly as granted. For a principal, row presence equals permission; a user's principals are themselves plus the groups they are in. - Effective access is computed in exactly one place,
services/access.ts, and every reader goes through it. Never add a second place that decides access. - Never materialize group access into per-user rows again.
- Never reintroduce per-user grant tables (the v1 Grants/ResourceGrants pattern).
- Preferences are
pref#rows: a different SK, so they cannot create a grant. - Anything that can end access goes through
accessNotices.withAccessDiff. - Tests seed
__tests__/helpers/fakeAccess.ts(an in-memory Access table) instead of stubbing Query or Scan of the table by hand. - Accounts and roles are registered by an admin (CDK, admin API or admin UI); there is no self-service flow to add them.
Kept in a separate stack from the compute so the durable data outlives any API redeploy. Tables reference each other by id (no duplicated data):
| Table | Key(s) | Holds |
|---|---|---|
| Accounts | PK accountNumber
|
registered AWS accounts (name, environment, …) |
| Roles | PK accountNumber + SK roleName
|
the assumable roles; roleArn lives here (single source of truth) |
| Access | PK principal + SK target, byTarget GSI |
access model v2 (2026-08-17) — grants exactly as granted: user#<sub>/group#<id> → role#<acct>#<name>/resource#<id> (attrs grantedBy, grantedAt, expiresAt?, seen flags), memberships user# → member#<groupId>, per-role prefs user# → pref#role#…. Effective access = own unexpired rows ∪ rows of every group the user is in — computed by services/access.ts (effectiveAccess/effectiveFor/holdersOf/snapshot), the ONE place that rule lives |
| Requests | PK requestId
|
access requests awaiting/holding a decision. byUser GSI = "what have I asked for?", byStatus GSI = the admin queue |
| Audit | PK eventId, byUser (subject) + byActor + byDay GSIs, TTL expiresAt
|
append-only activity log: one primary row per action (actor, action, subject, target, outcome, reason) written by the service that performs it, plus derived per-user rows (access.gain / access.lose) the access diff writes for group, cascade and bulk changes; rows from before the general log (vend-only) are read through an adapter; never read for an access decision; retention audit.retentionDays (default 400) past the 12-month review |
| Groups | PK groupId
|
group identity only (name, description, createdAt, createdBy); a group's bundle and members are Access rows (group#<id> → targets, user# → member#<id>). Nothing is materialized per member |
| Resources | PK resourceId (uuid) |
the network-resource catalog (Epic 4): what exists on the private network — account, cidr + ports (the ACL destination), display dnsName, connection instructions. Registering one grants nobody anything |
| ServiceUsers | PK clientId
|
registry of machine identities (M2M app clients): name, scopes, createdAt/By, lastUsedAt, rotation state (previousClientId on the current row / retiredInto on a replaced one). Auth requires the row to exist (delete = lockout on the next request), but it never decides grants — a service user's grants are ordinary Access rows under user#<clientId> (see "Service users" below) |
| Revocations | PK userId + SK noticeId (timestamp-first), TTL ttl
|
revoked-access notices for the activity bell. Expiry notices ride as seen-flags on still-existing grant rows, but losing access is a row delete — so every mutation that can end access (direct revoke, leaving a group, a bundle shrinking, group/role/resource delete, reapproval lapse) goes through accessNotices.withAccessDiff, which diffs each affected user's active targets before/after and writes a best-effort notice here only for what was really lost — and, since the activity log, one for what was really gained (change: GRANTED), except when the gain answers the person's own request (they get the decision instead). Served by GET /notifications/revocations (+ /seen); never read for an access decision; 30-day TTL |
| PluginCatalog | PK pluginId
|
deployment-written records of the installed plugins (Epic 5): revision, enabled flag, bound accounts, declared permissions, tombstoned or not — read by plugin discovery, the plugin authorizer and pluginAccess.ts, never user grants (those are plugin# rows in Access). Always present, feature on or off; no catalog record = no plugin grant authorizes |
| Tokens | PK tokenId, byOwner GSI, TTL ttl
|
personal access tokens: owner, name, scopes, optional role subset, expiry, lastUsedAt and the SHA-256 of the secret (never the secret). A token acts as its owner — it never decides grants; access is the owner's effective access narrowed in services/access.ts to the token's role subset. Revoking deletes the row. Always present, feature on or off (Personal Access Tokens) |
For a principal, row presence = permission for that principal; a user's
principals are themselves + the groups they are in. Absence is default-deny
(new users have nothing). Vending asks effectiveFor(user, role#…), then
resolves the ARN from the Roles catalog (falling back to the conventional ARN
if a role isn't catalogued yet). Users live in Cognito, not a table —
identity is the verified JWT, not a DB row.
Access vs Requests: Access is the answer ("may this user assume this role?"); Requests is the conversation that leads to it ("may I?"). A request never confers access — approving one writes an Access row, and Access is the only thing vending reads. Writing a request can't accidentally grant anything.
Scale note:
byStatuspartitions on a three-value key (PENDING/APPROVED/DENIED), so every pending request shares one partition. Fine at tens of rows (the queue drains as admins decide), but shard the key (e.g.PENDING#<n>) before request volume makes it hot.
Built and cut over 2026-08-17 with a one-off migration script. The v1 Grants/ResourceGrants tables stayed deployed but unread until 0.2.0 removed them (0.1.18 first dropped every other stack's reference to them, because CloudFormation refuses to delete an export a deployed stack still imports — upgrade through 0.1.18, never past it in one step).
Why: v1 materialized group access as ordinary Grants/ResourceGrants rows tagged
viaGroup, so one row must express three facts (held directly · held via
group(s) · both) and every mutation needs bespoke reconciliation
(applyGroupGrants skip/overwrite, removeGroupGrants re-tag via "coverage
by other groups", revoke hand-over). The state "direct AND via group" was
unrepresentable — revoking a direct grant deleted access a group still
promised (seen live 2026-08-17).
Design — grants are stored exactly as granted, in ONE table (Access):
PK principal
|
SK target
|
attrs | meaning |
|---|---|---|---|
user#<sub> | group#<groupId>
|
role#<acct>#<roleName> | resource#<resourceId> | plugin#<pluginId>#<acct>#<user|admin> | share#<shareId>
|
grantedBy, grantedAt, expiresAt?, (user rows: expiringSeen?, expiredSeen?, expiryLoggedAt?; share rows: ttl) |
a grant to that principal (a plugin# row authorizes only through pluginAccess.ts) |
sharedef |
share#<shareId> |
owner, label, port, siteId, expiresAt, ttl
|
a dev share's definition — not a principal, so never anyone's access |
user#<sub> |
member#<groupId> |
addedBy, addedAt
|
group membership |
user#<sub> |
pref#role#<acct>#<roleName>, pref#presence, pref#adminReview, pref#network, pref#notifications
|
profileName?, roleLabel?, … |
per-user preferences (their own rows — a preference write can no longer touch a grant, by construction) |
GSI byTarget (target → principal) answers "who holds X" (users AND
groups; groups expand to members via byTarget on member#<g>) and "who is
in group g". The Groups table keeps only {groupId, name, description, createdAt, createdBy} — a group's bundle and members are rows here.
Effective access = direct(user) ∪ ⋃ grants(group) for group in memberships(user); a row counts only while unexpired, whoever holds it
(admin-granted group rows carry no expiry; a dev share's group rows do). ONE function (access.effectiveAccess(userId)) computes it and every
reader uses it: vending (credentialsService), /accounts, /resources,
request eligibility, the reapproval sweep, expiry notices, the users
directory, grantee lists, and the ACL reconciler. Cost: 1 Query on the user's
PK (grants + memberships + prefs in one page) + one Query per group they are
in (single digits); the vending hot path (effectiveFor → effectiveForMany)
replaces the per-group Queries with one BatchGet of (group, target) keys — two reads.
Invariant, restated: for a principal, row presence == permission for that principal; a user's principals are themselves + the groups they are in. Absence is still default-deny; a request row never confers access; writing a preference never creates a grant (different SK).
What disappeared: applyGroupGrants/removeGroupGrants (+ resource twins),
coverage-by-other-groups, groupCoverage.ts, the viaGroup tag on rows
(direct/viaGroups are derived at read time and returned by the grantee /
per-user endpoints), and in 0.2.0 the v1 Grants and ResourceGrants tables
themselves.
Test helper: lambdacode/api/__tests__/helpers/fakeAccess.ts is an in-memory
Access table over aws-sdk-client-mock (install right after ddbMock.reset();
table-specific stubs declared afterwards still win). Seed rows instead of
stubbing Query/Scan when a test needs access state.
Revocation notices: a delete only ends access when nothing else covers the
target, so notices are computed at mutation time by diffing effective access
before/after for the affected users (direct revoke, membership removal,
bundle change, group delete, catalog cascades) — accessNotices.withAccessDiff.
Migration (a one-off idempotent script, deleted with the v1 tables): Grants rows
without viaGroup → user#+role# rows (attrs copied); ResourceGrants
likewise → resource#; Groups: roles/resources → group# rows, members
→ member# rows; rows tagged viaGroup are dropped when that group still
bundles the target for that member, else converted to a direct row (nobody
loses access). Preferences on Grants rows → pref# rows.
Resource grants follow the same lifecycle as role grants below: same two-phase
bell notices (via GET /resources/expiry + seen flags on the Access
row), same renewal/extension asks through the bell, and the same 12-month
reapproval sweep of standing direct grants (a resource-reapproval denial
revokes the direct resource grant; the network closes on the reconciler's next
pass).
An expired grant row is kept, not deleted: vending denies it (audited as
EXPIRED, distinct from NO_GRANT — an expiry denial is expected, not
suspicious), it stops listing on the accounts page, and re-approval simply
overwrites the row. In the request picker an expired grant no longer blocks
(re-request = renewal) while an unexpired temporary one can also be
re-requested (= extension ask) — approval overwrites either way; only
long-term access blocks a new request. The expiry bell is two-phase: a grant
alerts once when "expiring soon" (within min(24 h, half its lifetime), so a
1-hour grant alerts at 30 min, not at issue) and again for 7 days after it
expires, with separate expiringSeen/expiredSeen acknowledgement flags.
The daily sweeper covers standing grants — role AND resource rows:
long-term (no expiresAt), both a user's own Access rows and, since
2026-08-20, group bundle rows (one review per group×target, decided once
for all members; a lapsed group target is revoked from the group, and the
group's last target takes the whole group with it).
Interval 12 months, grace 14 days, both from requestsService. Approving a
REAPPROVAL request re-writes the grant (or re-stamps the group row), which
resets grantedAt — the clock restarts. Denying a REAPPROVAL revokes the
standing grant (unlike denying an ACCESS request, which changes nothing).
The sweep is stateless and idempotent: one open request per grant, and grace
is experienced, not computed — auto-revocation happens only after a
raised review sat open for the full 14 days (so a category newly entering
the sweep gets a visible review first, never a surprise revoke on deploy),
always via a denial recorded as system:reapproval so the audit shows it
wasn't a person.
Two raise-only yearly reviews ride the same sweep (2026-08-20) — the sweep never acts on these by itself; the pending request just waits:
-
Service users (
kind: SERVICE_USER, clock = last approved review or creation): approve stampsreviewedAt; deny DELETES the service user (secret dead on its next call, grants gone). Never auto-deleted on lapse — an unattended review must not kill a working automation. -
Admins (
kind: ADMIN, clock = thepref#adminReviewstamp on the admin's principal, written on approval — Cognito keeps no group-add timestamp, so the first sweep raises one per current admin): deny demotes from the admins group (refused for the last human admin — the request stays pending). Denying a service-user review keeps its DENIED row (the delete cascade clears pending rows only), so the decision stays on record; a deleted or shrunk group likewise clears its pending reviews so no ghost sits in the queue.
Pending role/resource reapprovals also carry usage (countRoleUsage
over the audit log's 400-day retention): "used N× this year" / "never used
this year" — decision support in the queue chip and dialog. Computed only
when the Requests page asks (?usage=1) and best-effort per row — the
bell's 60 s poll of the same endpoint never pays the audit walk, and a
failed lookup can't 502 the queue.
Humans get a lastSeenAt presence stamp on authenticated calls
(pref#presence row on the Access table — a pref SK, so it can never be a
grant; machines already had lastUsedAt). Throttled to one write per user
per 5 min per container; honest to within ~12 h even for parked sessions,
since the 12-hour refresh-token cap forces a real sign-in at least that
often. The Users detail panel shows it; tracking starts 2026-08-20, so
older activity reads "No activity recorded yet".
~/.aws/credentials profile names matter (cdk.json, scripts), so since
2026-08-18 they are resolved by the API in ONE place —
services/profileNames.ts, used by GET /accounts (profileName,
profileSource, suggestedProfileName per role) — and the desktop writes
exactly that string (no project prefix, no re-slugging):
- the user's own override (
pref#…profileName, set from the role card / credentials dialog; "↺ reset" clears it), - the account's admin-set
Accounts.profileName— only when the user holds exactly ONE role in that account (two roles can't share a profile), - the role's admin-set
Roles.profileName(its default), -
<accountNumber>-<roleName>slugged (the pre-2026-08 default).
Admin-set names (account-level AND role-level) must be unique across the
platform, case-insensitively — enforced on create/update
(adminService.assertProfileNameFree, 409) because they all land in the same
credentials file. Format: ^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$ (routes
validate; '' clears). Set them in Admin → Accounts (account panel row
"Profile name", role panel row "Profile name").
The profile-name override, the personal role label and the auto-vend star are
user#<sub> → pref#role#<acct>#<role> rows on the Access table. A
preference row is not a grant row (different SK — readers only treat
role#/resource# targets as grants), so a preference write can never
create access, by construction; the writes are plain upserts. Preferences
survive a revoke (harmless UI state; a re-grant finds them again).
None left to remember: a direct grant and group access are independent rows. Leaving a group removes one membership row; the user keeps anything they hold directly or through another group, and the loss diff decides the notice. A direct grant next to group access keeps its own expiry, and revoking it never touches the group's promise (the bug of 2026-08-17 that motivated v2). The "never downgrade" rule survives only in its narrow form: a temporary direct grant never overwrites a long-term direct one.
Deploy RolesStack into the target account (B):
aws sso login --profile sandbox-b
npx cdk bootstrap --profile sandbox-b aws://<ACCOUNT_B>/eu-central-1
npx cdk deploy Roles-<ACCOUNT_B> --profile sandbox-b # outputs RoleArn-<roleName> per roleThe account must be listed in rolesByAccount (that's what creates the
Roles-<account> stack); the deployed CloudFormation name stays RolesStack.
The role names are fixed (the Roles catalog stores their ARNs), so CloudFormation can never replace a role in place — the replacement would collide with the existing name. If a
RolesStackdeploy fails with an "already exists" error (e.g. after roles moved in code), destroy the stack and deploy it fresh; the role ARNs come back identical, so the catalog and grants in account A are unaffected.
Session length. Target roles are created with
MaxSessionDurationat the STS max (12 h), so the admin-set per-role session length in the app (900–43200 s, default 3600) is the effective limit;TargetRoleSpec.maxSessionDurationhard-caps a role lower in IAM if wanted. Roles deployed before 2026-08-26 still carry the old 1 h cap — picks longer than 1 h fail against them (the admin Test button and the vend/console errors say so) until theirRoles-<account>stack is redeployed. That redeploy is an in-place IAM update, no role replacement.
Then register the account + role via the admin API (or seed the Roles/Access rows)
and POST /credentials for it — aws sts get-caller-identity with the returned
creds reports <ACCOUNT_B>. The issuer URL derives from
PROJECT.issuer.domainName in config/project.ts — trust can't drift from
the issuer, and there is deliberately no override knob. Because that host no longer
changes when CredsStack is rebuilt, RolesStack only needs redeploying when the
roles/accounts here change — not on every issuer/CredsStack recreate as before.
Each target role's trust policy pins BOTH the audience and a role-scoped
subject: the issuer mints sub = "<account>/<role>/<userId>" and the trust
condition is StringLike <issuer>:sub = "<account>/<role>/*". A leaked or
replayed token therefore works against exactly one role in one account —
without the pin, every role in every target account trusts the same
issuer+aud and any minted token could assume all of them.
Rollout/redeploy ORDER (load-bearing):
-
CredsStack first (tokens gain the scoped sub; aud-only trust policies still accept them — the pin is additive).
-
Then RolesStack per target account (in-place trust update, no role replacement):
npx cdk deploy Roles-<ACCOUNT_B> --profile <account's profile>
-
Vend end-to-end per account afterward (role card → Get credentials →
aws sts get-caller-identity, or the admin Test button).
Reversed order breaks vending in that account (pinned trust rejects
old-format tokens) until CredsStack ships.
lib/__tests__/target-account-stack.test.ts asserts the condition so it
can't silently regress.
Source: wiki/ in FNTIO/aws-infrastructure-client, mirrored by the Wiki workflow. Edit the files there; changes made on this site are overwritten by the next sync.
Start here
Use
How it works
Operate
Contribute