Security
The worker never holds a key worth stealing.
Most breaches that begin with a machine credential begin the same way: a long-lived IAM access key, scoped more broadly than anyone intended, sitting on a host that nobody has rotated in two years. Auritus is built so that credential does not exist. A worker authenticates as a person once, then carries a one-hour token that renews itself and cannot reach AWS at all.
The problem being solved
Two ways to let a machine call your service.
The difference is not that one is managed more carefully. It is that the risks people manage carefully in the first case are absent in the second.
Risk moved into the architecture
Fewer things an operator can get wrong.
An IAM access key is dangerous less because it is weak than because keeping it safe is an ongoing human obligation. Someone has to write a tight policy, resist widening it when something breaks at 2am, rotate the key on schedule, and remember every host it was copied to. Each of those is a place an organization can quietly fall behind, and none of them announce failure.
Auritus removes the obligations rather than documenting them. The long-lived artifact on the machine is a Cognito refresh token, which is not an AWS credential and cannot be presented to any AWS API. The credential that does reach the service expires in an hour. Rotation is a property of the refresh exchange, so it cannot be skipped under load. What remains is a single decision, made once, about who is allowed to be an operator.
How the worker stays authenticated
One login, then indefinitely, if it keeps trying.
The thirty-day number is not a deadline for the operator. It is the longest the worker may stay silent.
The mechanics
Why a thirty-day token lasts forever.
An operator runs auritus login once. Cognito returns an access token valid for one hour and a refresh token valid for thirty days, cached in a mode-0600 file. Before the access token expires the CLI exchanges the refresh token for a new pair, with no browser and no prompt.
The part that matters is rotation. The user pool is configured to return a new refresh token on every exchange, so each successful renewal resets the thirty-day clock. A worker refreshing hourly is never within twenty-nine days of expiry. The thirty-day limit only applies to a worker that has been powered off, offline, or otherwise unable to reach Cognito for a month.
That boundary is signposted rather than sprung. Starting forty-eight hours before expiry, the worker emails the operator, at most once a day. If the refresh token is already dead it emails again and exits with a distinct status code so a supervisor can surface it. That alert route is deliberately unauthenticated: a worker whose token has expired cannot present one, which is exactly when it needs to ask for help. Abuse is bounded by confirming the address belongs to a real Cognito user and by a per-recipient rate limit.
Operator identity
Three ways to decide who may be an operator.
All three converge on the same Cognito pool and therefore the same short-lived, rotating, API-scoped token. Only the question of who gets in changes. Their implementation status differs, and is stated with each.
Option one — Available today
Native Cognito users.
The user pool holds the operator accounts directly. Self sign-up is disabled, so accounts exist only because someone with access to your AWS account created them. This is the simplest path inside your AWS account, requiring no external identity provider.
Option two — Supported (SSO)
Google Workspace.
The stack wires a Google OAuth identity provider into the Cognito user pool. Operators authenticate with their Google account via the web console or CLI browser sign-in (`auritus login --sso google`), inheriting your Google directory MFA, password policies, and immediate offboarding controls.
Option three — Supported (SAML 2.0 / SSO)
AWS IAM Identity Center or any SAML provider.
For organizations running workforce identity centrally, the Cognito user pool connects directly to AWS IAM Identity Center (AWS SSO) or any corporate SAML 2.0 provider (Okta, Entra ID, Ping). Operators sign in via single sign-on (`auritus login --sso aws-sso`), keeping operator credentials under enterprise audit governance.
Guarantees
What the design promises.
Scope is structural, not a policy
The operator token is a Cognito JWT accepted only by the Auritus operator routes. It cannot call AWS APIs at all. There is no policy document to get wrong, and no scope that can quietly widen over time.Rotation happens on its own
Each silent refresh issues a new refresh token with a fresh 30-day clock. A running worker stays authenticated indefinitely without a human, and without anyone remembering a rotation date.Revocation is one command
Token revocation is enabled on the user pool, so auritus logout invalidates the refresh token at Cognito rather than waiting for it to age out. That is the primary stolen-token control.Boundaries
What is not true yet.
Everything above describes the architecture. One part of it is not fully enforced in the current implementation, and we would rather say so here than have you discover it in the source.
The API authorizer does not verify token signatures yet. It checks that a bearer token is present, that it is shaped like a JWT, and that the issuer and audience claims match this deployment. Those claims are not secret, so a forged token carrying the right values would currently be accepted. Full RS256 verification against the Cognito JWKS needs a Lambda layer with the signing libraries, and it is the next piece of this work. Until it lands, treat the operator API as protected by obscurity of the endpoint rather than by the token.
The claims that do hold today are the ones about what is absent: the worker is issued no IAM user, no access key pair, and no static API key, and the token it does carry cannot call AWS APIs. A leaked refresh token has the blast radius of a leaked access token, longer lived, and is revocable with auritus logout.