Service Accounts

[GregorShear]

Summary

• Adds service accounts: non-login identities (backed by auth.users rows) that authenticate via API keys and are authorized through the existing user_grants / role_grants system.
• Adds one new table, internal.service_accounts and adds the column public.refresh_tokens.created_by.
• Adds GraphQL mutations createServiceAccount, addServiceAccountGrant, removeServiceAccountGrant, createServiceAccountToken, revokeServiceAccountToken, and a paginated serviceAccounts query.
• Adds a fine-grained ManageServiceAccount capability (included in the TeamAdmin bundle) that gates service-account management.

Key design decisions

• Service accounts are auth.users rows. All existing RLS policies, PostgREST authorization, user_roles() resolution, and role_grants traversal work unchanged. Each account gets a synthetic, non-login address (<catalog_name>@service.estuary.dev) and stores its catalog name as full_name.
• catalog_name is a management anchor It is unique and determines who may manage the account (admins of a covering prefix, via ManageServiceAccounts) and how the account is addressed.
• Access is governed solely by the service_account's user_grants, which may span multiple prefixes.
• Authorization is split to prevent privilege escalation. Managing an account (create, mint/revoke keys, add/remove grants) requires ManageServiceAccount on the catalog name. Adding a grant additionally requires CreateGrant on the granted prefix, so a caller can't hand a service account reach they couldn't grant anyone. Removing a grant requires only management capability, since narrowing access is always safe.
• Creating a grant where one already exists overwrites the old one (i.e. you can downgrade capabilities this way)

Test plan

• Create service account with grants → mint refresh token → exchange for an access token via POST /api/v1/auth/token
• A caller without ManageServiceAccount cannot create, or manage service accounts
• addServiceAccountGrant requires CreateGrant on the target prefix; removeServiceAccountGrant does not
• refresh token validFor validation: reject non-ISO-8601 durations, non-positive durations, and durations over 1 year
• serviceAccounts query is scoped to the caller's ManageServiceAccounts prefixes
• Duplicate catalogName is rejected with a clear error

[GregorShear]

I have mixed feelings about doing this in the create mutation - maybe we need an "update grant" mutation that lets us downgrade capabilities, and the create mutation just upserts (upgrade capabilities only)?

[GregorShear]

let's talk about this

[GregorShear]

moving this flaky test to the end of the line, at least for now