The identity stack
| Layer | Provider | What it does |
|---|---|---|
| User identity | Clerk | Email, password, MFA, SSO (where configured), session lifecycle, organization membership. |
| AWS authorization | AWS Cognito Identity Pool | Exchanges a Clerk JWT for short-term AWS credentials scoped to the user’s current organization. |
| API gateway | AWS AppSync (GraphQL) + custom Lambda authorizer | Validates the Clerk JWT on every request, enforces organization membership, scopes resolvers to the caller’s org. |
| Resource ACLs | AppSync resolvers + DynamoDB row-level checks | Enforce ownership, organization scope, custom share grants. |
Sign-in flow
Sign in with Clerk
Studio opens a Clerk sign-in surface. Clerk handles password, MFA, SSO if configured by the org admin.
Receive a Clerk session
The Electron renderer holds the Clerk session. Studio requests JWTs from Clerk for the downstream services it needs to call, with the user’s organization claim populated.
Exchange for AWS credentials
The Clerk JWT is exchanged with the Cognito Identity Pool for short-term AWS access credentials valid for the lifetime AWS sets.
Tag the credential with the organization
The Identity Pool’s principal-tag mapping reads the organization claim from the Clerk JWT and attaches it as an AWS principal tag on every signed request.
Sign AWS calls
AppSync, KMS, and Bedrock calls are signed with the temporary credential. Server-side IAM policies and KMS key policies condition on the principal tag, so a credential issued for org A cannot read resources or decrypt material belonging to org B.
Why two systems instead of one
Clerk gives us first-class organization, role, and session management — including hosted MFA and SSO — without us having to operate it. Cognito Identity Pool is the only AWS-native way to convert a third-party JWT into short-term AWS credentials with attribute-based authorization. Wiring the two together means:- We get the user-facing experience and security features of a dedicated identity vendor.
- We get AWS-native enforcement of organization scope at the IAM and KMS layers, not just at the application layer.
- A Clerk session revocation cuts AWS access at the next credential refresh — there is no long-lived AWS key to chase.
Sign-out and revocation
Local plaintext is purged
On the desktop, the sign-out routine purges every
vault:* entry from the OS keychain, including cached plaintext data keys, and zeros the Go sidecar’s in-memory copy.Cached AWS credentials expire
The AWS credential cache holds the last issued credential until its natural expiry, typically within an hour. New requests cannot be signed after that.
Org admin can force-revoke
From the Clerk dashboard, an org admin can invalidate all sessions for a user (e.g., on departure). Combined with a DEK rotation, this guarantees the departed user cannot decrypt new envelopes even if they kept a copy of an old DEK.
Organization isolation
Every record in Studio carries anorgId. Three layers enforce that boundary:
- AppSync custom Lambda authorizer. Every GraphQL request hits a Lambda that validates the Clerk JWT, extracts the active
org_id, and refuses requests where the caller’s organization does not match the requested resource’s organization. - Resolver-level filters. Every list/get/update operation is rewritten so the
orgIdfilter is non-negotiable. Strict mode rejects any query that attempts to filter on a differentorgId; lenient mode (used during the rollout) logs and rewrites. - KMS key policy condition. The per-organization customer master key in KMS will only decrypt for callers whose AWS principal tag
orgIdmatches and whosekms:EncryptionContext:orgIdmatches the wrap. Even if a resolver or DynamoDB row leaked, decryption would fail.
Resource-level access inside an organization
Within an organization, four scopes apply to most resources (hosts, diagrams, procedures, memories, conversations, files):| Scope | Who can see it |
|---|---|
| Private | Only the owner. |
| Org | Every member of the organization. |
| Custom share | The owner plus a list of explicit members granted by the owner. |
| Inherit | Resolved at read time from the parent folder’s scope. |
ResourceShareMember rows with a role per member. Folder-inherited visibility resolves at read time so a folder change applies to all descendant items without a backfill.
The same scope mechanism applies to encrypted material. A custom share triggers the resource DEK re-wrap so the recipient’s organization can decrypt the shared resource using its own KMS key, without exposing the originating org’s DEK.
The desktop sidecar’s identity
The Go sidecar that runs SSH, packet capture, and other local operations does not have a separate identity to AWS. It runs in the same process group as the Electron parent, inherits the same operating-system trust, and is reached only over a localhost loopback bound to the parent’s PID. AWS-side calls always originate from the renderer process with the user’s short-term credentials. This is a deliberate choice. Adding a second identity for the sidecar would expand the attack surface without adding meaningful protection — the sidecar already holds plaintext keys in memory at the moments when the user authorized it.Federation and SSO
SSO is configured at the Clerk layer per organization. Clerk supports SAML and the major OIDC providers (Microsoft Entra, Google Workspace, Okta). When SSO is in place:- The Clerk session lifetime is governed by the org’s SSO policy.
- MFA is the SSO provider’s MFA, not Clerk’s.
- Sign-out propagates from the SSO provider to Clerk to Studio’s AWS credential cache.
Related
Vault and keys
Where the per-organization KMS keys live and how they enforce isolation cryptographically.
Audit and telemetry
What’s logged about authentication and authorization events.