Guards

Permissions are checked before guards. A request your permissions refuse never reaches the rules, so a guard can only narrow access. It can never grant what a permission refused.

The reverse holds too: a request that is unauthenticated on purpose, such as sign-up, is allowed by a permission and so reaches the guards. That is what makes a rule like "registration is closed" possible.

Rules never apply to requests authenticated as the service administrator, which is how the console reaches the service. So Guards are safe to experiment with: a rule that blocks everything still leaves the console working, and you can always go back and fix it.

A request that is unauthenticated on purpose reaches the guards: a permission allowed it, so the rules get their say. That makes "registration is closed" possible, and it is also the easiest mistake to make in a condition.

A rule on a user’s state runs the same comparison for a caller who has no user, finds it false, and acts. The effects vary:

Guard the rule with @authenticated:

You could instead exclude every public path by name, alongside /auth and /token. It works, but you only notice the list when it is wrong, and it grows each time something else becomes reachable without an account, including endpoints a feature registers on its own.

For users authenticating with a JWT, @user holds the token’s claims only. A condition on @user.latestConsents never matches unless latestConsents is one of the claims your service issues.

Set the claim list with Settings on the Users page (see Users). The Guards page warns you, under the condition, when it names a field that is not in the list.

Users authenticating with username and password are not affected: for them @user is the full user document.

Two fields on the user document:

There are two flags because the terms and the privacy policy have versions of their own. The same request accepts both: the client does not choose what it accepts, and that keeps this to one permission and one rule. An acceptance that can be split (the privacy policy mandatory, the terms optional) needs a different design, with a permission and a rule per flag.

POST /auth/register writes neither field, and their absence is exactly what the guard blocks on. There is one way to accept, the PATCH of step 2, the same whether the user has just signed up, arrived through OAuth, or has had an account since before the current version.

Add a JSON Schema on /users (see Schemas) that validates the two fields when present. Do not make them required: their absence is the state the guard exists to catch. The schema also declares OAuth fields (socialAuths, profile.avatarUrl) and team fields (teams, team) as optional, so documents created via OAuth or after team operations pass validation.

On the Schemas page, Create schema takes the schema _id in its own field and the schema body in the editor. Through the API it goes in the body like in any other MongoDB document: POST /schemas with {"_id": "userConsentsSchema", …​}.

Schema id: userConsentsSchema

Schema document:

The two _id are different things: the one in the form field identifies the schema, the one under properties describes the _id of a user document, the email.

The user accepts with a PATCH /users/{userId} on their own document. No permission allows that request out of the box, and the guard never sees a request the permissions refused: without a permission of your own the acceptance is a 403 and the user is locked out for good.

restheart-accounts does install a rule of its own on /users, a veto: it denies self-service writes to _id, password, roles, team, teams, sub, socialAuths, providerId and the one-shot token fields. A veto never grants. Every other field, consents included, is left to your permissions.

Create the permission on the Permissions page (see Permissions):

The request the client sends is then:

A few things are doing work here:

Add both latestConsents/tos and latestConsents/pp to the JWT claims, with Settings on the Users page (see Users), so the condition also holds for users authenticating with a token.

The rule must exempt the request the user sends to accept: the PATCH of step 2. bson-request-whitelist(consents) scopes the exemption to exactly that request, so the rule does not open up self-service writes to any other field.

The same condition, broken up as it reads:

A JWT is a snapshot taken when it is issued. After a user accepts, the token they hold still says they have not, and the rule keeps blocking them. So the acceptance has to be followed by a new token.

Which request you make depends on what the client is holding.

Holding a bearer token, the usual case right after an acceptance: add ?renew=true to get a new one without sending the credentials again:

This request is made while the user is still blocked: the token it carries says they have not accepted. That is why /token is among the exclusions of the condition. Without it the acceptance can never take effect.

Authenticating with credentials: ?renew=true is not needed. Every GET /token authenticated with Basic credentials is a fresh issuance built from the user document as it is read at that moment:

The renewed token is built from the user document read again from the database, so it carries latestConsents as it is at that moment, along with any other change, including the user’s roles.

Often better: have the acceptance endpoint return the new token in the same response. That is what restheart-accounts does when a user switches team or activates their account. It saves a round trip, and the user never passes through a state where they are blocked by a decision they have already made.

Signing out and back in works too.

Five requests, on a test account that has not accepted yet. Run them in order: one that does not answer as described tells you which piece is wrong.

Then check the user document: latestConsents carries the versions and an acceptedAt written by the server, and consents gains one record per acceptance.

The application never checks whether the user has accepted. It reacts to being told:

Nothing in the client compares versions. That is what keeps the two sides from drifting: raise the version in the rule and in the permission, and every client starts seeing 451 on the next request, with nothing to rebuild or redeploy.